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First, our legal stuff... 


ROGER WAGNER PUBLISHING, INC. 
CUSTOMER LICENSE AGREEMENT 


IMPORTANT: The Roger Wagner Publishing, Inc. software 
product that you have just received from Roger Wagner 
Publishing, Inc., or one of its authorized dealers, is 
provided to you subject to the Terms and Conditions of 
this Software Customer License Agreement. Should you 
decide that you cannot accept these Terms and Condi- 
tions, then you must return your product with all docu- 
mentation and this License marked "REFUSED" within the 
30 day examination period following the receipt of the 
product. 


l. License. Roger Wagner Publishing, Inc. hereby 
grants you upon your receipt of this product, a 
nonexclusive license to use the enclosed Roger Wagner 
Publishing, Inc. product subject to the terms and 
restrictions set forth in this License Agreement. 


25 Copyright. This software product, and its 
documentation, is copyrighted by Roger Wagner Publish- 
1ng, Inc. You may not copy or otherwise reproduce’ the 
product or any part of it except as expressly permitted 
in this License. 


3. Restrictions on Use and Transfer. The original and 
any backup copies of this product are intended for your 
personal use in connection with a single computer. You 
may not distribute copies of, or any part of, this 
product without the express written permission of 
Roger Wagner Publishing, Inc. 


LIMITATION ON WARRANTIES AND LIABILITY 


ROGER WAGNER PUBLISHING, INC. AND THE PROGRAM AUTHOR 
SHALL HAVE NO LIABILITY OR RESPONSIBILITY TO PURCHASER 
OR ANY OTHER PERSON OR ENTITY WITH RESPECT TO ANY 
LIABILITY, LOSS OR DAMAGE CAUSED OR ALLEGED TO BE CAUSED 
DIRECTLY OR INDIRECTLY BY THIS SOFTWARE, INCLUDING, BUT 
NOT LIMITED TO ANY INTERRUPTION OF SERVICE, LOSS OF 
BUSINESS OR ANTICIPATORY PROFITS OR CONSEQUENTIAL 
DAMAGES RESULTING FROM THE USE OR OPERATION OF THIS 
SOFTWARE. SOME STATES DO NOT ALLOW THE EXCLUSION OR 
LIMITATION OF IMPLIED WARRANTIES OR LIABILITY FOR 
INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THE ABOVE 
LIMITATION OR EXCLUSION MAY NOT APPLY TO YOU. 


Then Apple’s... 


DOS 3.3 Standard is a copyrighted program of Apple Com- 
puter, Inc. licensed to Roger Wagner Publishing, Inc. to 
distribute for use only in combination with The Database 
Toolbox. 


APPLE COMPUTER, INC. MAKES NO WARRANTIES, EITHER 
EXPRESS OR IMPLIED, REGARDING THE ENCLOSED SOFTWARE 
PACKAGE, ITS MERCHANTABILITY OR ITS FITNESS FOR ANY 
PARTICULAR PURPOSE. THE EXCLUSION OF IMPLIED WARRANTIES 
IS NOT PERMITTED BY SOME STATES. THE ABOVE EXCLUSION 
MAY NOT APPLY TO YOU. THIS WARRANTY PROVIDES YOU WITH 
SPECIFIC LEGAL RIGHTS. THERE MAY BE OTHER RIGHTS THAT 
YOU MAY HAVE WHICH VARY FROM STATE TO STATE. 


And from DSR... 


This disk contains a high speed-operating system called 
Diversi-DOS(tm), which is licensed for use with this 
program only. To legally use Diversi-DOS with other 
programs, you may send $30 directly to: DSR, Inc., 5848 
Crampton Ct., Rockford, IL 61111. You will receive a 
Diversi-DOS utility disk with documentation. 


Diversi-DOS(tm): Copyright 1982 DSR, inc. 


And now on with our program! 


a. , UY yy ‘ie = a. x hin Aa naeagea pa a, fi #,_, fi fi ft» fa fa A 


“= 


ewww eww 


weseoev»4e#»#w»4esges & 


Se © 


oO 8 


oS wo 


ws 


@ 


ABOUT THE AUTHOR 


Steve Cochard holds a degree in Civil Engineering 
from Penn State University and had been a Structural 
Engineering Group supervisor for Bechtel Corporation 
before becoming the vice-president of Roger Wagner 
Publishing. His interest in computers dates back to a 
1964 tour of an Army main frame installation. He bought 
his first micro in 1978 and has been programming ever 
since. He has developed various application packages, 
an assembler, a student financial aid data base called 
Study Money, and The Database Toolbox. A California 
resident, Steve enjoys photography, wood-working, and 
skiing as much as_ possible with his wife Sharon, and 
their children, Jason and Alyson. 


[ i {] 
Jue 


6 &eeoeoegweuweweweweswe 


wo © © & 


ww 


it 


@e we 


An extensive library of 


*x*k* THE DATBASE TOOLBOX *** 


with Applesoft Basic. 


By Steve Cochard 


TABLE OF CONTENTS 


array-related 


commands for use 


INTRODUCTION . ....... 


How to use this manual . .« 
Your Diskette ...... 
Special DOS Features .. . 
A Short Demonstration .. 


If It 


Doesn°t Work ... « 


Adding More Routines .. . 


TOOLBOX 


LIBRARY FILES 


General Library Information. 
The Database Toolbox: General Syntax 
How to Use the Library Documentation 


Notes 


LIBRARY 


ARRAY 
ARRAY 


ARRAY 
ARRAY 
ARRAY 
ARRAY 
ARRAY 
ARRAY 
ARRAY 
ARRAY 
ARRAY 


on Array Subscripts. 
FILES 


READER . - « + «© « « 
WRITE . -« « « « «© 


SEARCH . . - «© » « « 
SORT . 2. «© ee we wo 
DELIMITED STRING . 
RENAME . « «© «© « « « 
CLEAR . «+ «eee 
DELETE . - «+ «= « + 
REDIM . 2. « » ew o 
TRANSFER «. - « « © 
ROW COL ADD ... . 
ROW COL KILL... . 
RND. « «© «© © © © @ « 
FUNCTIONS SINGLE . . 
FUNCTIONS .... - 


FUNCTIONS PARSE . . 
STR$§ . © © « © wo © 
VAL « «© we we we we ew 
ROUNDING . ..... 


TITLE 
MATRIX IDENTITY - - - + + © = © © = 
MATRIX TRANSPOSE . - - - + + © = + ¢ 
MATRIX MULTIPLY -- + + + + 2+ © © + 


MATRIX INVERSE - - - -+ -+ + + © + © 


USR MACHINE MODULES 


USR MACHINE. ~. - - «© © © © © © © © & 


USR Functions. . - - « «= © «+ «© © «© & 
WORD PEEK LOG 10 DEG RAD 
ARC COS ARC SIN SECANT 
COTANGENT COSH SINH 


REPAIRS TO APPLESOFT 


RND FIX . - © © © © © © © © © © © 
ONERR FIX . «+ 2 © «© © © © © © © 
RETURN FIX . «© «© «© «© © © © © © © © 
GARBAGE MAN. . . - «© © © © © © © © 


“EXTRAS” 


DISK START.TB. « - - © © © © © © @ 
FAST RUN.TB. «- - «© © © © © © © © © 
FAST BRUN.TB . ~ « © © © © © © © © 
RESTORE AMPERSAND.TB . - - - - «© « © 
BEEP.TB . -2 © © «© © © © © © © © @ 


OTHER WORKBENCH OPTIONS 


Adding Commands. . . . .- + + + « « « 
Removing Commands. . .- +--+ + +s © 
Copying All Commands to Disk... .- 
Restoring Commands from Disk... .- 
Report Commands Added. . -- +--+. + 
Search for Added Commands. ....- - 
The Memory Map. .- + + + «© ee ee © 


APPENDICIES 


A: Advanced Array Reading and Writing 
B: Advanced Use of the WorkBench. . . 
C: A Little More Detail ......-. 


D: Using the Toolbox and Workbench with 


DATABASE TOOLBOX QUICK REFERENCE LIST. 


li 


ProDOS. 


. 


56 
58 


, ——~ 


=a a an haa Ma 7 a a ae Se ae ar a wa fF 


~ 


vowvw 


{i 


aye 


wy & 


Gg wa aw 


So 8 © S&S wecst we 


w 


e 2 © 


@ 


WELCOME TO THE DATABASE TOOLBOX 


The Database Toolbox is a programmer’s dream. Ie 
appeals to beginning and intermediate, as well as 
advanced programmers. 


This Toolbox is a collection of nifty commands you 
can add to Applesoft to make writing ANY program quick 
and easy. It is viewed by many people as the "“Applesoft 
Construction Set”. YOU build your program out of the 
Toolbox”°s extensive set of “program building blocks" 
called Toolbox files. And, you select only those new 
commands that YOU need for your program. 


How does it work? First you decide which new command 
you'd like to have. Then you take out your Toolbox 
and go to the Workbench. The Workbench will get 
the tool from the Toolbox and add your new command to 
Applesoft AND your program. 


Better yet, you won’t waste any time by trying to find, 
research, write or debug the most needed parts of your 
programs. If for example, your program needs to know how 
to sort, you simply use the Toolbox and Workbench 
to add a sort command. You can sort all your names and 
addresses with one simple Applesoft program line: 


100 & "SORT", LISTS$(1) TO LIST$(100) ON NAMEZ(0) 
And it’s many times faster than Applesoft! 


There are four different Toolboxes available. Each 
comes with the Workbench and from 25 to 40 new and 
exciting commands for Applesoft. 


The Database Toolbox includes over 40 list or array- 
related functions, including searching, sorting and many 
different kinds of list or array manipulations. 


The Chart “n Graph Toolbox has over 40 graphics and 
charting commands. The Video Toolbox contains over 
30 Text Screen input and output commands. The Wizard’s 
Toolbox offers more than 30 assorted commands including 
Print Using, Sound Effects, Hi-Res Text, Turtle Graphics 
and more. 


Get your hands on a Toolbox, and youll NEVER 
program without it again! 


HOW TO USE THIS MANUAL 


This manual may seem to be a bit large and over- 
whelming at first. However, after reading just a few 
pages that will give you an overview of the Toolbox, you 
should be able to do just about anything you need by 
reading only a few small_ sections that describe what 
you’re interested in at the time. 


The manual is divided into two main parts. First is 
a section explaining the workings of the Toolbox and 
Workbench. The second section explains how all of the 
commands in the library work and how to use them. There 
are also appendices in the back. 


The first thing to do is read the introductory 
information on The Database Toolbox for a little general 
knowledge of your diskette. Then make a copy of your 
diskette using any normal copy program. Next, boot’ the 
Database Toolbox on your computer and follow the 
demonstration given in the "A SHORT DEMONSTRATION” 
section of the manual. Just go through the first four 
pages of the demonstration since you don’t need to know 
anything else at this point. 


When you have completed the demonstration run the 
demo programs on the back side of the disk to see what 
your new commands will do. Then go through the table of 
contents and look for the commands that interest you and 
read the sections of the manual devoted to those 
commands. 


That“s all you need to do to use the Database 
Toolbox. The sections describing each command should be 
read prior to using the commands, but you don“t need to 
understand everything. You can get by with a minimum of 
knowledge and a little experimentation. 


The manual”s appendices will describe the other 
slightly more advanced features of the Toolbox that may 
come in handy as you progress in your programming. 
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YOUR DISKETTE 


You do not have to boot on_ the Database Toolbox 
diskette to use any of the programs on the diskette. If 
the power was not previously on, or if you wish to 
install the modified DOS used on _ the Database Toolbox 
diskette, you may however boot in the usual manner. This 
will not affect any programs you may wish to run later. 


IMPORTANT: It is strongly advised that you do not use 
your originally purchased diskette, in either the ex-— 
amples that follow, or your daily use of the Database 
Toolbox. Imstead, make a back-up of your disk. The 
original should then be put ina safe place, and the 
back-up used as your work diskette. After making your 
work diskette, return to this section. 


In addition, the backside of the Database Toolbox 
diskette contains a number of demonstration programs, 
which will provide some insight as to the possible uses 
of the Toolbox*’s commands. 


SPECIAL DOS FEATURES 


If you do boot on the Database Toolbox diskette, a 
special Disk Operating System (DOS) will be in effect 
which you may find to be of some advantage. 


The first thing you will notice is a number just to 
the right of the “RWP VOLUME 254° message. This is the 
number of free sectors remaining on the diskette being 
CATALOGed. A normal Apple DOS 3.3 diskette has a maximum 
of 496 free sectors available. 


The second feature is an optional termination of the 
CATALOG listing at any of the pauses which usually occur 
when a catalog has more files than can be displayed on 
the screen at one time. When using the modified DOS, 
pressing RETURN will terminate the CATALOG listing at any 
pause. Pressing any other key will continue it. 


A SHORT DEMONSTRATION 


The primary purpose of the Database Toolbox is to add 
new commands to your own Applesoft programs, as_ easily 
and efficiently as possible. 


The Toolbox uses a utility called the Workbench to 
actually add the new commands to your programs. The 
Workbench is located on side l of your Database Toolbox 
diskette. To use it, all that you have to do is: 
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1) Insert one special line in your program that is 
provided on your disk which tells Applesoft you have 
added some new commands to your program. 


2) Use the Workbench utility to add the commands of 
your choice. 


3) Use these commands from within your Applesoft 
program by using the ampersand followed by the name of 
the new command. 


To see how this works, let~s consider an actual 
example. Let~s suppose for a moment that you would like 
to have some kind of musical sounds in a program you are 
writing. The entire process can be done in less than a 
minute: 


1. Type in NEW to clear any program in memory. 


2. With the Database Toolbox disk in the drive, type in 
EXEC AMPERSAND’ SETUP. Then type in LIST and 
you should see: 


1 CALL PEEK(175) + 256 * PEEK(176) — 46 


When your program is run this’ line will connect 
Applesoft to the various Toolbox commands you have 
added. 


3. Get the Workbench installed by typing in: 


BRUN WORKBENCH 


After a few seconds the main menu will appear: 
**k*k TOOLBOX WORKBENCH *** 
SELECT AN OPTION: 


ADD A COMMAND 

REMOVE A COMMAND 

REMOVE ALL COMMANDS 

COPY ALL ADDED COMMANDS TO DISK 
RESTORE COMMANDS FROM DISK 
REPORT COMMANDS ADDED 

SEARCH FOR TOOLBOX COMMANDS 
DISPLAY MEMORY MAP 

EXIT 


COnNDULF WNP 
. 


[NO COMMANDS ADDED] 
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4. Since the first thing we want to do is to add a new 
command to our program, press “1°. The screen will 
then display: 


INSERT DISK WITH TOOLBOX FILE TO BE 
ADDED, THEN ENTER NAME OF FILE 


(“CAT“ FOR CATALOG, <RETURN> TO QUIT) 


TOOLBOX FILENAME -—> 


If you knew that TONE.TB was the file for the 
command you wanted to add at this point, you could just 
enter the name directly. Often you will not know the 
Mame exactly, in which case you can enter “CAT” to 
produce a catalog of the diskette. Enter “CAT” now. 
Since BEEP.TB is further down the list, press the space 
bar (not RETURN) for the next page of the catalog, and 
continue until you can see BEEP.TB. Now press RETURN to 
stop the catalog (assuming that you have booted with the 
Database Toolbox diskette). 


5. Now type in BEEP.TB as the Toolbox File to be 
loaded. Then press Return. Note that all Toolbox 
File names have a ~.TB” suffix. 


Next the screen will display: 
YOUR COMMAND NAME -> 


6. You must now enter the new name which you will use 
for this command within your program. Because the 
Toolbox Files themselves may have rather long names 
(so as to be most descriptive) you will often want to 
use a shorter name when using the routine from within 
your program. In this case, “TONE” will do nicely. 
Type in TONEF as the name and press RETURN. 


The Workbench will now load the BEEP.TB routine, and 
add the command “TONE” to your program. 


After the command is added, the program will return 
to the request for a new FILENAME. This is because 
usually you will want to add several commands at one 
time. Press RETURN alone to return to the menu at this 
point. 


7. Now enter “O° and press RETURN to exit the Workbench 
and return to your program. 
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8. When using these new commands in your Applesoft 
programs, a special “syntax”, or command structure, 
is required. Each Toolbox command has either two or 
three parts, as follows: 


The first part required is the ampersand symbol (&).- 
You can think of this as being similar to the Control-D 
character needed whenever a disk command is done. The 
difference here is that the ampersand will call a Toolbox 
command. 


The second item required is the command name (in 
quotes) for the routine you wish to call. For our 
example, this would be “TONE”. If the command which you 
have just added does not require any information to be 
passed to it, then nothing more is required in the 
command. 


The third item is optional, and is referred to as a 
“variable list™. Each Toolbox command may or may not 
have certain pieces of information which have to be 
passed to it. In the case of the BEEP.TB routine, this 
information is pitch and duration. (In the case of other 
commands, the variable list following the name may have a 
different number of variables required and use a_ variety 
of variable types.) 


To use your new “TONE” command in a program, you 
would first determine the values for pitch (P) and 
duration (D), such as through an INPUT statement, and 
then call the command via the ampersand statement. To 
show how this might be done, enter the following program 
lines (these will now be in addition to the line #1 which 
was previously entered via the AMPERSAND SETUP procedure 
above): 


10 INPUT “ENTER PITCH, DURATION: "; P, D 


20 & “TONE”, P, D 
30 PRINT: GOTO 10 


9. Now just RUN the program to try it out! Enter: 


10,10 
50,10 
100,20 


as some sample number pairs. Its that easy! 


A 


7 a a a or or Vr Va vr war Var ar war a a Ta a Ta” wa ta Ta a 


nH @& 


ey 


© © e& & &Fe&aaewe 


o oO & & 


ee we 


By the way, remember that, like normal Applesoft, 
you can use any variable names you want in calling a 
command. As long as you include the type of variables 
that the command expects, the variable name (or expres— 
sion) is up to you. 


YOU“RE DONE! You now have aé_é complete program. 
The program can be LOADed or SAVEd just like any normal 
Applesoft program, and the new commands will be carried 
along automatically. They will remain a permanent part 
of your Applesoft program, unless you decide later to 
remove them using the Workbench “Remove a Command” 
option. 


If you want to add more commands later, just BRUN 
WORKBENCH again, and add the commands you want. See _ the 
section at the end of this manual to determine the exact 
syntax for using each command. 


SPECIAL TIP: FAST RUN METHOD 


If you have booted on’ the Toolbox diskette, then you 
can take advantage of its special DOS to make using the 
Workbench even easier. 


This is done by using the “wild card" option built 
into the DOS. When typing the name of a file, you can 
use just the first few letters of the name followed by an 
equal sign ("="). For example, if you wanted to BRUN the 
Workbench, you could just type: 


BRUN WORK= 


This tells DOS to BRUN the first file in the catalog 
starting with the letters “WORK”. The “=" is called a 
wild card because it can represent any combination of 
remaining letters in the name. 


Because the Workbench, Ampersand Setup, and Remove 
Workbench are the first files on the diskette catalog, 
it gets even easier to use them: 

To install the Workbench, just type: BRUN W= 

To add the Ampersand Setup line, type: EXEC A= 


To remove the Workbench, type: BRUN R= 


IF IT DOESN°T WORK 


In order for your program to use an added command it 
must meet two conditions: The ampersand must have been 
set up before any Toolbox command is executed in your 
program, and there must actually be an added Toolbox File 
with the name used in your command. If either of these 
conditions is not met, your program will crash 
unceremoniously. 


THE AMPERSAND LINK. It is good practice, when 
developing a program which will use Toolbox commands, to 
BEGIN by EXECing the AMPERSAND SETUP file. As explained 
earlier, this inserts a line (with line #1) in your 
program which tells Applesoft that you are using the 
Toolbox commands. : 


This line can occur anywhere in your. progran, 
provided that it is executed prior to the first Toolbox 
command. If it is not present then youll probably get a 
SYNTAX ERROR when you try to use one of your new 
commands. If this happens when you run your program, 
check to make sure the ampersand setup line is present 
AND being executed prior to the Toolbox command. 


THE TOOLBOX FILE. Another way to _ bomb your program 
is to attempt to use a Toolbox command which has not been 
added. In this case (assuming that the proper setup line 
has been inserted) your program will try to find the new 
command named by you among the commands added. When it 
doesn’t find it, you will get an UNDEFINED FUNCTION error 
message. You can then determine which Toolbox command is 
missing. 


If you are sure that both the ampersand link and 
added command are present, then double-check the syntax 
(and perhaps the sample program listing) for the command 
as listed in the section on Toolbox Library Files in this 
manual. 


ADDING MORE COMMANDS / RESUMING NORMAL OPERATION 


If you want to add a new command right away, type in 
CALL 2051 to re-enter the Workbench. If you”re done 
using the Workbench for a while and want to free up the 
memory normally occupied by the Workbench utility, type 
in: BRUN REMOVE WORKBENCH. This will remove the 
Workbench from memory. 
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The Workbench utility is required in memory only 
when you are adding or removing commands (or doing any of 
the other things that it allows you to do). It is not 
required to be in memory when you run your program. —~— _ 


After you have added a command with the Workbench, 
you may exit and immediately run your program (with the 
Workbench still present). 


If you are using Hi-Res graphics you should remove 
the WORKBENCH. To remove it BRUN REMOVE WORKBENCH as 
described above and then run your program as_ usual. 
IMPORTANT: If you are using Hi-Res graphics, be sure 
to read the section on the MEMORY MAP option of the 
Workbench! 


If you need to know more about the memory usage by 
the Toolbox and Workbench see “A Little More Detail” in 
Appendix C of this manual. 


You” ve now learned most of what it takes to use and 
enjoy the Toolbox system. The next section describes the 
commands that have been included in this package. Their 
wide variety makes the Database Toolbox of immediate 
value in your programming efforts. 


If you are impatient and wish to get your hands on 
the Toolbox commands right away, then go ahead - it’s 
quite friendly. At some time, however, the section in 
this manual on the complete Workbench options should be 
read, as it does provide much useful information on _ how 
to get the most out of this unique programming tool. 


DEMONSTRATION PROGRAMS 


There are a number of demonstration programs on the 
back of the Database Toolbox package. These were created 
using the Workbench to add commands from the Toolbox 
Files on the disk. These programs may be LISTed and 
studied to see exactly how the added commands are used 
within an Applesoft program. 


IMPORTANT NOTE: The Workbench utility may be used to 
append ANY ampersand-called machine language routine to 
an Applesoft program, and is not limited to the Toolbox 
Files available on this Database Toolbox disk or other 
Toolbox disks. This means it is possible to use 
routines that you have written yourself, or are listed 
in magazines. The only requirement is that the routine 
be location independent (i.e. it can’t have JMP“s and 
JSR’s to labels within the routine itself). 
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>> THE DATABASE TOOLBOX LIBRARY COMMANDS << 
by Steve Cochard 


The basic philosophy behind the Database Toolbox disk 
is three fold: 


First, to add commands to Applesoft that greatly 
simplify programming and add extreme power and speed to 
your programs. 


Second, to provide a library of fast, easy-to-use 
commands that are common to many programs (i-.e-., sorting, 
searching, etc.) and which will allow you to concentrate 
on the specific application rather than wasting time 
“re-inventing the wheel” by writing, for example, yet 
another sort command. 


Finally, to provide commands that will allow 
programmers at all skill levels to simply and quickly add 
a “professional touch” to their programs. 


GENERAL LIBRARY INFORMATION 


The Toolbox library of commands is directed mainly at 
arrays and array manipulation. In addition, several 
other types of commands are included which are useful in 
database applications. 


The array commands range from simple time savers 
(CLEAR), manipulation commands (REDIM, ROW COL ADD & 
KILL, RENAME), memory management (DELETE, REDIM), vector 
oriented commands (FUNCTIONS, RND) to sophisticated 
processing commands (READ, WRITE, SORT, SEARCH, MATRIX). 


Also included are assorted USR functions. These are 
included to accomplish three goals: 


1) Add needed functions to Applesoft 
2) Stimulate interest in this little used function 
3) Give the USR MACHINE something to do! 


Let°s turn to the Library in general and look at a 


few hypothetical programs and the commands they might 
use. 
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CHECK BOOK PROGRAM: 


READ - Gets the checks into memory fast 

WRITE - Write them back to disk, pronto! 

SORT - Every check book needs to be sorted 

SEARCH - Look for tax deductions 

CLEAR - Get ready for the next batch of checks 

REDIM - Easily add new records without having to 
provide extra unused space for expansion 

GAME : 

FAST BLOAD - Load Hires pictures in less than 2 
seconds (from the Wizard”~s Toolbox I 
disk) 

RND - All games are random, arent they? 

FUNCTIONS - For those sines & cosines so necessary 
for Enterprise and Klingon course 
corrections 


ENGINEERING AND SCIENTIFIC: 


READ - For speed and “special” abilities 

WRITE - For speed; number crunching takes enough 
time 

FUNCTIONS - Why use loops, when you can do math 


operations on entire arrays just like the 
vector-oriented super computers 
USR MACHINE - To use USR 


TANH - For hyperbolic calculations 
SINH - More hyperbolics 

RAD DEG - Most people like degrees 
MATRIX - To solve all of those equations 


Depending on the application, different commands will 
be desired, and that°s the beauty of the Database 
Toolbox. YOU decide which commands you need and _ which 
you don’t. 


THE DATABASE TOOLBOX: GENERAL SYNTAX AND YOU 


This manual, and in particular the syntax of each 
command, was painstakingly designed with the programming 
novice in mind. The commands, however, were designed to 
satisfy the needs of the most demanding programmer. The 
syntax of all the commands parallel equivalent Applesoft 
commands as far as possible; differences are clearly 
noted in the documentation. 


ll 


Take, for example, the DISK STARTUP.TB command. This 
command allows the use of optional variables like the DOS 
“CATALOG” command : 


DOS Command: 
CATALOG ,S5,D2 


TOOLBOX Command: 
& "START" ,5,2 


The DOS example shows that two variables have been 
specified, (slot and drive number). Two variables have 
also been specified for the Toolbox command. 


The syntax of the commands, in general then, is as 
follows: 


& “COMMAND” [,expression] and/or [,variable] 


“COMMAND” is the name assigned to the command when it 
is added to the Applesoft program by the Workbench. Some 
commands have variables or expressions after the command 
mame and some don’t. Of the commands that do, commas are 
required after the command name to separate variables and 
expressions. 


HOW TO USE THIS MANUAL 


Each command in the Database Toolbox has a section in 
this manual devoted exclusively to it. Each of these 
sections is designed to be independent of all the other 
sections. 


The description for a command consists of five 
sections: Function, Syntax, Sample Statements, How to 
Use It and Sample Listing. When appropriate, additional 
sections will be included, such as Limitations, Errors, 
etc. 


When you first read the following sections, it is 
suggested that you briefly skim over each entry for the 
various commands, generally noting the basic purpose and 
function of each command. This will give a quick 
overview of the contents and capabilities of the library. 
If, after reviewing the sections, youre interested in 
more detail about a particular command, re-read the 
description of that command. After using the library 
commands for a time and becoming familiar with them, the 
quick reference section at the very end of this manual 
should provide the basic reminders for the syntax and 
name of each command as it is needed. 
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The “SYNTAX” section of each description uses the 
“metalanguage” notation used on pp. 30-35 of the Apple- 
soft Basic Programming Reference Manual. This is done 
for completeness, compactness and continuity between 
Applesoft and “our™ language! For those not inclined to 
use this method of explanation, complete examples are 
also provided. 


The “How To Use” section of each description is more 
than just directions on how to include a command in a 
program. It also includes information suggesting WHEN to 
use a command and WHY to use it. This approach will help 
the programming novice gain additional insight into the 
Datbase Toolbox’s many uses. 


NOTES ON ARRAY SUBSCRIPTS 


Upon reviewing the descriptions for the various 
commands you will notice a difference in how some of the 
commands “look” at array subscripts. Some commands deal 
with entire arrays, i-e. CLEAR, DELETE, etc., while some 
commands deal with part of an array or even single array 
elements. The documentation for the commands will spec- 
ify a dummy subscript if it doesn°t care about the 
subscript. For example, the command “DELETE” ,A(10,10) 
makes little sense within the context of the DELETE 
command (this command deletes an ENTIRE array). 


In general, any command which applies to an entire 
array will use a dummy subscript of (0) after the 
variable name to indicate that the variable is indeed an 
array. Functions which deal with ranges though, such as 
SORT, SEARCH, etc., usually allow you to specify the 
starting and ending elements of the array in which the 
action is to be performed. For example, for the SEARCH 
command, the notation “A(10) TO A(20)" would be expected. 
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>> ARRAY READER.TB << 
by Steve Cochard 


FUNCTION: This command will read a sequential text file 
from disk into either a string or real (floating point) 
array. 


SYNTAX: & “NAME”, sexp, sexp, [aexp,] avar, avar 
[,array var] 
& "NAME", option, filename [,records to skip], 
records to read, error return variable 
[,array to read into] 


SAMPLES: & "READ", "R", “TEST FILE",N,E,AS$(1) 
& "READ", O$, “TEST FILE”,N,E%,A(1,1) 
& "READ", "M", FS,S,N,E,A$(1,1) 
& "READ", “N", FS,N,E 

Where: 


-"R" is the “read” option, 

-"TEST FILE” is the file name, 

-N is the number of records to read, 

-E is the error return variable, 

-A(1,1) and A$(1) and A$(1,1) are the arrays to 
receive the records, 

-O$ demonstrates use of a string variable or 
expression to specify the desired reading option 

-"M" is the “mid-file” read option, 

-S is the number of records to skip during a mid- 
file read, : 

-E% shows integer variables. 

-"N" is for the “number of records in file” option. 


HOW TO USE: There are three things you can do with 
this command: 1) Read from the beginning of the file (R), 
2) Read from the middle of the file (M) and 3) Count the 
number of records in a file (N). Let’s look at each of 
these options and the variables associated with them. 


BEGINNING OF FILE READ OPTION 


This option will read N number of records into the 
specified array, starting at the array element selected 
by the user. 


SELECTING THE OPTION: Any string expression’ that 
(when evaluated) begins with "R", such as "R", "READ", or 
X$ (where X$="R") will select the beginning of file read 
option. 
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FILE NAME: This may also be any string expression. 
The length of the string must be 30 characters or less, 
which is the maximum length of a DOS file name. Note 
that the specified file must be a TEXT file. Non-text 
files will be ignored by ARRAY READER.TB. 


RECORDS TO READ: This may be any real or integer 
variable. If this variable evaluates to zero, ARRAY 
READER-TB will attempt to read the entire file until the 
file is read, the array is filled, or memory is used up. 
If the variable does not evaluate to zero, the specified 
number of records will be read, unless the array or 
memory are filled first. When the command is finished 
reading the file, the actual number of records read is 
returned in the variable used in the variable. In the 
previous samples, "N” would return that value. 


ERROR RETURN VARIABLE: This may be any real or 
integer variable. One of the following error codes is 
returned in this variable by the command when it finishes 
reading the file: 


O = No error; normal exit 

1 = Out of memory error; will only occur when reading 
into a string array 

= End of file 

= End of array 

= No buffers available; close a file or use greater 
maxfiles 

5 = Disk I/O error while reading the catalog 

6 = File not found 

7 = Disk I/O error while reading data from file 


ARRAY TO READ INTO: This may be any string or real 
array (i-e., using a variable name that does not end with 
"Z") of any size with any number of dimensions. Take 
special note of the fact that the subscripts used are NOT 
dummy subscripts and are used to specify where in _ the 
array to start placing data. 


MID FILE READ OPTION 


This option will skip S number of records in a file 
and then read N number of records into the designated 
array. 


To use this option just use a string that begins 
with "M" for the option and insert the "S" variable to 
indicate the number of records to skip. An explanation 
of the command’s variables that need changing follows. 
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SELECTING THE OPTION: Any string expression that 
(when evaluated) begins with "M", such as "M", "MID", or 
X$ (where X$="M") will select the mid-file read option. 


RECORDS TO SKIP: This may be any arithmetic expres— 
sion, variable or constant. This variable specifies the 
number of records to skip before reading. 


RECORDS TO READ: Similar to the “READ” option, except 
for the following: If this value is zero, ARRAY READER.TB 
will attempt to read all remaining records in the file. 
If it is not zero, the value is interpreted as the record 
number in the file at which to stop' reading. For 
example, if it was desired to skip the first 10 records 
and then read the next 10, the value of "S" would be set 
to 10 while the value of "R" would be set at 20. If "R” 
is less than "S", no records will be read, unless "“R"” 
equals zero (in which case the remainder of the file 
would be read). 


COUNT NUMBER OF RECORDS IN FILE OPTION 


This option will simply count the number of records 
in a file. A record is defined as text which is 
terminated by a carriage return. Another way to look at 
this is simply counting the number of carriage returns in 
a file. 


To use this option, simply use a string that begins 
with "N" for the option, set the number of records to 
read to zero. Remember to use the syntax given 
previously since some variables are not needed. An 
explaination of the command’s_ variables that need 
changing follows. 


SELECTING THE OPTION: The "N" option is specified to 
select this option. The remaining discussion under 
“READ" also applies to this variable. 


NUMBER OF RECORDS TO READ: This variable must 
evaluate to zero. If it is not zero, then the command 
will simply count until it reaches the specified number 
of records and then return. 


TECHNICAL NOTES: This command uses an input routine 
similar to that found in the STRING INPUT.TB command on 
the ROUTINE MACHINE disk. That is, it considers all 
characters in a record valid characters and will never 
result in an Applesoft "?EXTRA IGNORED" error due _ to 
commas, etc. 
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Note that this command does not OPEN and CLOSE text 
files in the normal sense of the words. When DOS OPENs a 
file to read, it remains open until it is closed by the 
program. ARRAY READER only OPENs the file long enough to 
read what it needs, then it immediately closes the file. 
What this means to the user is that it is not possible to 
use ARRAY READER in conjunction with other DOS commands 
as it is with ARRAY WRITE. It also means that you do not 
have to use DOS to OPEN a file prior to using ARRAY 
READER, or to CLOSE the file after using it. 


For more advanced information regarding the reading 
and writing of multi-dimensional arrays, see Appendix A. 


Sample Listing: 


10 FS$="TEST FILE": R=0: E=0: O$="N":REM SET UP 

20 &"READ”,0$,F$,R,E : REM FIND NUMBER OF RECORDS 

30 O$= “R": REM SET UP TO READ NOW, “R~ HAS # OF REC’S 
40 DIM A$(R): &"READ",0$,F$,R,E,A$(1):REM READ “EM IN! 
50 FOR I = 1 TO R: PRINT AS(1): NEXT:REM PRINT “EM! 


LIMITATIONS: This command will not’ read into integer 
arrays. The command will not interface with DOS com- 
mands. This command will not work with ProDOS. 


>> ARRAY WRITE.TB << 
by Steve Cochard 


FUNCTION: This command will write the contents of any 
string or real (i-e., no “%" sign in the variable name) 
array to a specified sequential text file at extremely 
high speed. The range of data elements within the array 
may be specified as well as the size and location of the 
data buffer used by ARRAY WRITE. 


SYNTAX: & “NAME” ,sexp,sexp,avar,array var TO 
array var [,aexp [,aexp] ] 
& “NAME",option, file name, error return var, 
start of array end of array [,start of buffer 
[,end of buffer] ] 


SAMPLES: & “ARRAY WRITE" ,0$,FS$,E,A(1) TO A(10) 


& “ARRAY WRITE" ,0$,FS,E,A(1) TO A(10),ST 
& “ARRAY WRITE" ,0$,F$,E,A(1,2) TO A(50,50),ST,EN 
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Where O$ =the desired option 

FS =the name of the text file to write to 

E =the error return variable 

A(1) =the starting array element to write 

A(10)=the ending array element to write 
(all elements in between are written also) 

ST =decimal address of memory location for the 
start of the data buffer. Data will be 
stored temporarily from here to FRETOP (start 
of string storage) until the write has been 
completed. When completed, the memory will 
be released for normal use by the user. Note 
that any data stored within the buffer or 
machine language subroutines will be 
overwritten by data on its way to the disk. 

EN =decimal address of memory location for the 
end of the data buffer. Data will be stored 
from ST to EN. This syntax also illustrates 
the use of the command with multi-dimensioned 
arrays. 


HOW TO USE: This command should be used any time it 
is desired to write an array to a sequential text file. 
It can be used in place of the usual DOS commands to OPEN 
and WRITE a file. ARRAY WRITE.TB will open the file 
specified, write the desired string or real (floating 
point) array to disk and return to the Applesoft program. 
It is important to note that this command DOES NOT close 
the file! This must be done using a DOS CLOSE command in 
order to assure that all of the data is written to disk. 


The following sample program will illustrate the 
steps required to write an array to a text file: 


10 O$="WRITE":FS="TEST FILE":DIM AS$(20) 


- (work on the array AS) 


100 & “ARRAY WRITE” ,0$,F$,E,A$(1) TO AS$(20) 
110 PRINT D$"CLOSE" : REM DS = CONTROL D 


Take note that the standard DOS CLOSE command is used 
to close a file written by ARRAY WRITE.TB. 


You might be wondering, “Why is it necessary to CLOSE 
a file written by a command such as ARRAY WRITE.TB?" This 
is done to allow a great deal of flexibility when using 
ARRAY WRITE.TB. 
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There are two options available when using ARRAY 
WRITE .TB. “W" for write and "C" for continue writing. 
The difference between the two options is that "W" will 
OPEN and then WRITE an array to a non-existent or to a 
closed file, while "C" will WRITE an array to an OPEN 
file. This allows many options when using this command. 
Let”s examine some of the options available to you. 


1) Open a file, write an array and close the file. This 
is the simplest use of the command. To do this, the same 
program steps as shown in the samples would be used. 


2) Open a file, write an array, write another array and 
close the file. To exercise this option, the only 
difference from the above example is to add another 
&"ARRAY WRITE” statement with the "C” option prior to 
closing the file: 


10 O$= “W": FS$= “TEST FILE" 
20 &"ARRAY WRITE” ,0$,F$,E,A$(1) TO AS(10) 


30 O$="C" 
40 &"ARRAY WRITE” ,0$,FS,E,B$(1) TO BS$(50) 
50 PRINT D$ “CLOSE” 


3) Open a file, write an array, write simple variables, 
write another array, close the file. This type of 
writing requires intermixing DOS WRITE commands with 
ARRAY WRITE.TB. This also illustrates the compatibility 
of open files with both DOS and ARRAY WRITE.TB. 


10 & “ARRAY WRITE”,"W",FS,E,AS(1) TO A$(10) 

20 PRINT DS$;"“WRITE";F$:PRINT E,A,B,D,ES$ 

30 & “ARRAY WRITE", "C",FS,E,C1$(1,1) TO Cl1$(50,10) 
40 PRINT DS; “CLOSE”; FS 


4) Open a file using DOS, write simple variables, write 
an array, close the file. This illustrates the ability 
to write to an open file using ARRAY WRITE.TB. 


10 PRINT D$"OPEN"FS$ 

20 PRINT DS$"WRITE"FS 

30 PRINT A,B,EC,A$(5),A1$ 

40 & “ARRAY WRITE", "C",F$,E,Z$(1) TO Z$(20) 
50 PRINT D$; "CLOSE" 


5) Append an array to an existing file. This requires 


use of the DOS APPEND command in conjunction with ARRAY 
WRITE.TB. 
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10 PRINT D$;"APPEND"FS 
20 & “ARRAY WRITE”,"C",FS,E,A$(1) TO AS$(100) 
30 PRINT D$;“CLOSE” 


The previous five samples are meant only to 
illustrate potential uses of ARRAY WRITE.TB, with and 
without DOS. Remember, the "“W" option should be used to 
start (open) a new file, the “C" option should be used to 
write to an open file- All of the other DOS commands 
that position the "file marker” may also be used just as 
APPEND was used above. 


ERRORS: The error return variable will return the 
Status of any attempted write. The error codes it 
returns are identical to the DOS error codes. If the 
error return variable contains any value greater than l, 
then something unusual has_ happened. Note that error 
codes of O and 1 are considered normal. Refer to the DOS 
manual for a description of possible errors and their 
codes. 


STRING TOO LONG error will occur if the file name is 
greater than 30 characters, which is the maximum length 
DOS allows for a file name. BAD SUBSCRIPT error will 
occur if the subscripts used are larger than the dimen- 
sions of the array. 


Any error associated with expressions may occur if 

the buffer limits, ST & EN, are used. Refer to the 
Applesoft reference manual for descriptions of these 
errors and their cause. 
TECHNICAL NOTES: In 99% of the cases, the starting 
and ending addresses of ARRAY WRITE.TB’s data buffer do 
not have to be specified (see example #1). When these 
addresses are not given the command will use the free 
memory existing at the time the command is exercised as 
its buffer. 


For a full explanation of the ARRAY WRITE.TB data 
buffer and when its limits may need to be specified, see 
Appendix A. 


LIMITATIONS: This command will not work with ProDOS. 
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>> ARRAY SEARCH.TB << 


by Peter Meyer and Craig Peterson 


FUNCTION: To search a one- or two-dimensional STRING 
array for the occurrence of a _ specified string, sub- 
string, or a Boolean relationship between the search 
string and the found string. 


SYNTAX: (one-dimensional array search) 


& “NAME",first element to search/ element # found 
[,last element] ,string to search for, [char 
posn] [,beg byte] [,search type] 


& “NAME” ,array svar (avar) [TO array svar 
(aexpr)], sexpr, [,avar] [,aexpr] [aexpr] 


SYNTAX: (two-dimensional array search) 


& “NAME",row to search, first column to search 
/ element # found, same row to search, last 
column to search, 
|first row to search / element # found, column 
to search, last row to search, 


same column to search, string to search for 
[,char posn] [,beg byte] [,search type] 


& “NAME",array svar (avar,avar) TO array svar 
(aexpr,aexpr), sexpr, [,avar] ({,aexpr] [,aexpr] 


SAMPLES: (one dimensional arrays) 
& “ARYSRCH",AS(FE) ,KWS 


=> Puts in “FE” the element number of array AS$() 
where string “KWS$° was found. 


& “ARYSRCH",AS(FE) TO AS(LE),KWS$,CP,BB,ST 


=> Puts in “FE” the element number of array AS() 
where string “KWS° was found, when the search 
was started at byte position “BB° within each 
string. Search type is either “full” or 
“initial” depending on value (0-5) of “ST”. 
On return CP = position in the string at which 
KWS was found. 

& "ARYSRCH",AS(FE) ,KWS, ,BB 
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=> Search for KWS$ starting at FE-th element. 
Examine each element beginning with the BB-th 
character and going through the rest of the 
string. Search to the end of the array, and 
don“t bother to return the position at which 
the search string was found. 


& “ARYSRCH" ,AS(FE) ,KWS,,,3 


=> As above, with the exception that no byte 
position is specified, and search type is 
“3°. 


HOW TO USE IT: ARRAY SEARCH.TB allows you to search 
quickly through a one- or two-dimensional string array, 
not only for identical matches, but also for “relational” 
matches, that is, “greater than” or “less than” relation- 
ships between the search string and the strings in the 
array. 


The simplest form of the use of this command is as 
follows: 


& “ARYSRCH", AS(FE), KWS 


This may be interpreted as: Search through the array 
AS(), beginning with element AS$(FE), looking for the 
first occurrence of KW$. On _ return, FE will be negative 
if KW$ was not found. Otherwise FE will be set to the 
index of the element in which KWS was found. 


The command returns when it finds an occurrence of 
KWS$, and so does not in itself return ALL occurrences of 
KWS in the array AS(). This can, however, be 
accomplished simply by repeated use of the command. For 
example, the following line will display ALL occurrences 
of KWS$ in an array BS from the lst element to the 100th 
(assuming that the length of B$ is at least 100): 


200 FE =1 

205 & “ARYSRCH", BS(FE) TO BS(100), KWS$: IF (FE < 
O ) THEN PRINT BS(FE): IF NOT FE < 100 THEN FE 
= FE + 1: GOTO 205 


If you wish to know the position in the string at 
which KWS$ was found then add an extra variable to the 
variable list, so: 


& "ARYSRCH", AS(FE), KWS, CP 
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On return, CP will be zero if KWS$ was not’ found, 
otherwise it will be such that KWS occurs at the CPth 
position in AS(FE). 


If you want to begin searching within each string 
from some position other than the first byte, include one 
more variable in the variable list, so: 


& “ARYSRCH", AS(FE), KWS$, CP, BB 


BB is the Byte-to-Begin variable, and must be in the 
range 1 <= BB <= 255. 


So far, all examples have been requests for a “full” 
search, meaning that each string in the specified search 
range is examined from the BB-th character to the end of 
the string. Thus, if we were searching for "CAT" with BB 
= 5, the keyword would be found in an element such as 
“DOGS AND CATS" (and on return CP, if included in the 
variable list, would be set to 10). (KWS = “DOG" would 
not be found if BB = 5.) 


But perhaps we wish to know if “CAT" occurs, not just 
somewhere in the string at or after the BB-th byte, but 
SPECIFICALLY AT the BB-th byte. This is a different TYPE 
of search, and so we must include yet another variable in 
the variable list, so: 


& “ARYSRCH", AS(FE), KWS, CP, BB, ST 


ST is the Search Type, and can have any integer value in 
the range 0 - 5. ST =O means a full search, meaning 
(as explained above) that it will look through the entire 
string for the keyword. If ST > O then each string will 
be checked for the keyword at the BBth position, or if 
BB is not specified, at the beginning of the string. 


If ST > O then the command will return when it finds 
a substring XS at the BB-th position in some element in 
the array satisfying the following: 


If ST = 1 then X$ = KWS 
If ST = 2 then X$ < KWS 
If ST = 3 then X$ <= KWS 
If ST = 4 then X$ > KWS 
If ST = 5 then X$ >= KWS 


ARRAY SEARCH.TB allows you to default on variables in 
two ways. The first method is simply not specifying all 
of the variables. All variables given must be in the 
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correct order, but if you stop the list then the 
remaining variables are given their default values. 


The second method is to create a dummy entry for a 
variable by omitting the variable name where it would 
have appeared. This allows you to default on some 
variables early in the list while still being able to 
give non-default values to variables later in the list. 
For example, to default on all variables except the 
search type one would use a module command such as: 


& “ARYSRCH", BS(1), KWS, , , ST 
The default values for the variables are as follows: 


LE = last element in the array 
BB = 1 (first character in each array element) 
ST = O (full search) 


LIMITATIONS: The relational searches mentioned above 
ino e string comparisons only, e.g. “CAT” < “DOG”. 
Searches which involve numerical comparisons, e.g.: 


23 << 45 <¢ 231 


will function properly provided that the numbers are 
represented as strings left-—justified with zeroes so that 
they have a common length, as in: 


"0023" < "0045" < "0231" 


The starting element must be specified as AS(FE), 
with FE defined appropriately. FE cannot be replaced by 
a number, since the command returns with a value in FE. 


SAMPLE PROGRAM: (one-dimensional array searching) 


5 CALL PEEK(175) + PEEK(176)*256 - 46: TEXT:HOME 
10 FOR I = 1 TO 10: FOR J = 1 TO 8 
20 AS(L) = AS(I) + CHRS(48 + RND(1)*10): NEXT I 
30 PRINT I; HTAB 5: PRINT AS(1): NEXT J: POKE 34,11 
40 INPUT “DIGIT(S) TO FIND? ";KW$: IF KWS = "" 
THEN POKE 34,0: END 
50 FE = 1: & “ARYSRCH", AS(FE), KWS, CP, 2: 
REM NOTE BB = 2 
60 IF FE < 0 THEN PRINT “NOT FOUND";: GOTO 80 
70 PRINT "FOUND"; 
80 HTAB 15: PRINT "FE = ";FE;" CP = ";CP 
90 PRINT: GOTO 40 
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TWO-DIMENSIONAL ARRAY SEARCHING: 


In general, two-dimensional array searching follows 
the same rules as those previously discussed for one- 
dimensional searching. 


The main differences between the two types of 
searches are: 


1. Two array subscripts are used instead of one. 

2. The “TO” portion of the search MUST be used. 

3. Only ONE row or ONE column may be searched at a 
time. 


SAMPLES: (two-dimensional arrays) 
& “ARYSRCH", AS(ROW,CS) TO AS(ROW,CE), KWS 


=> The above example searches through row “ROW” of 
array A$(), from starting column “CS~ to ending 
column “CE”, looking for the string specified 
by “KWS°. If the string is found, the element 
number of its position within the array is put 
in CS. If the string is not found, a negative 
number is put in CS. 


& “ARYSRCH", AS(RS,CLMN) TO AS(RE,CLMN), KWS 


=> The above example searches through column 
“CLMN” of array AS(), from starting row “RS~ to 
ending row “RE”, looking for the string 
specified by “KW$~. If the string is found, 
the element number of its position within the 
array is put in RS. If the string is not 
found, a negative number is put in RS. 


SPECIAL NOTE REGARDING SEARCHING ONE ELEMENT: 


If you specify the same number for both row and 
column, (i-.e., just one element within the array), the 
result of the search will be stored in the FIRST array 
subscript. You can force the result to be stored in the 
second subscript by encasing the first subscript with 
parentheses or by using a number for the first subscript 
instead of a variable. 


SAMPLE PROGRAM: (two-dimensional array searching) 


100 CALL PEEK(175) + 256*PEEK(176) - 46 
105 : 
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110 
120 
130 
140 
150 
160 
170 
180 
190 
200 
210 
220 
230 
240 
250 


260 


LET AS$(1,1)="DOG" : A$(1,2)="CAT" 
LET AS(2,1)="BAT" : A$(2,2)="HAT" 
LET AS(3,1)="RAT” : AS(3,2)="VAT" 


LET RS=1 : RE=4 : CS=1 : CE=4 


INPUT “WORD:";KWS 

FOR ROW=(RS) TO (RE) 

: LET CT=CS 

: & “ARYSRCH", AS(ROW,CT) TO AS(ROW,CE), KWS 
: IF CT >= 0 THEN FOUND=1:RF=ROW:CF=CT:ROW=RE 
NEXT 


IF FOUND THEN PRINT “FOUND AT ROW ";RF;", 
COLUMN ";CF 
IF NOT FOUND THEN PRINT “NOT FOUND" 


Note concerning the previous sample program: 


-A FOR NEXT loop (statements 190-230) is used to 
search the entire array by searching every row, 


-The row end (RE) and column end (CE) can be set to 
be greater than the actual size of the array (state- 
ments 180-190), 


-°CT° in statement 220 must be set to its original 
value (statement 200) every time it is used in the 
loop, because the results of the search are stored in 
it, 


-The meaning of the variable names are: RS=Row Start, 
RE=Row End, CS=Column Start, CE=Column End, KWS = 
Keyword, CT=Column (Temporary holder), RF=Row Found, 
CF=Column Found. 
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>> ARRAY SORT.TB << 
by Paul Spee and Leo Krabbendam 


FUNCTION: Quickly sorts a one- or two-dimensional 
string, real or integer array using the Shell-Metzner 
method and the use of multiple key fields in either 
ascending or descending order. 


SYNTAX: & “NAME”,first element to sort, last element 
to sort, keyfield to sort 
& “NAME",array var(aexp,0) TO array var(aexp,0) 
ON array name%(0) {two dimensional} 
& “NAME",array var(aexp) TO array var(aexp) 
ON array name%Z(0) {one dimensional} 


SAMPLE: KEY%(0)=1:KEY%(1)=1:& "ARYSORT", NS$(1,0) TO 
NS$(100,0) ON KEY%(0) 
&"ARYSORT",X(1,0) TO X(500,0) ON K%(0) 
&"ARYSORT” ,Z%(0) TO Z%(100) ON K%(0) 


HOW TO USE IT: Suppose we have a mailing list which 
we want to sort by zip code and we want people with the 
same zip code to appear alphabetically by last name. 


ARRAY SORT.TB allows you to perform this sort very 
quickly and with a great deal of flexibility: you can use 
a large number of key fields (up to 127) and any keyfield 
sort can be in ascending or descending order. 


Let°s assume that the mailing list contains the 
following information: 


First name <--Field 1 
Last name <--Field 2 
Street Address <--Field 3 
City <--Field 4 
State <--Field 5 
Zip code <--Field 6 


The above six lines of information are collectively 
called a “record”, while each line is called a “field.” 
Each person in the mailing list, then, has ONE record, 
composed of SIX fields. 


This can be represented conveniently in Applesoft by 
using a two-dimensional array, with the first dimension 
representing the record number and the second dimension 
reprsenting the field number. An array containing the 
records of three people, then, would be created like 
this: 
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DIM AS$(3,6) 


1 | No. of fields 
No. of records----- ----- per record 
(people) in list 


The first field that we want to sort on, zip code, is 
called the “primary key” or “primary keyfield”. Then we 
want all people with the same zip code to be sorted by 
last name, the “secondary keyfield". We need to give 
ARRAY SORT.TB that information in the form of a 
one-dimensional integer array (you may name it anything 
you like, but we~1l call it “KEY” for our purposes here): 


KEY%(0) = 2 : KEY%(1) = 
| 


| 
No. of keys-------- | 
| 


—-—-—>o 


Primary key (key #1)-------- 
Field no. (zip code)------------- 


Secondary key (key #2)-------------------- 
Field no. (last name) =====-=-===—===s=--—=-=— 


To sort the entire array, you would enter: 
&"ARYSORT", AS(1,0) TO A$(3,0) ON KEY%(0) 
Notice the following about the use of this command: 


-The second dimension in each array name and the 
number in the “KEY%" name MUST be zero. 

-The “KEY%Z(0)" (or whatever name you choose) must be 
an INTEGER (i-e. uses the "%" symbol) array. 

-The KEY% field MUST be dimensioned to the number 
of fields you have. For example, if you have 7 
fields, you MUST specify DIM KEYZ(7). 

-Variable names can be used for beginning and ending 
element numbers in the arrays. 


Now, suppose your mailing list has a lot of people 
with the same last name and zip code. In this case, we 
would need to set up a third keyfield, street address. 
This is how you would set up the keys: 
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KEY%Z(O0) = 3 <--Number of keys 

KEY%(1) = 6 <--Primary key (zip code) 
KEY%(2) = 2 <--Secondary key (last name) 
KEY%(3) = 3 <--Third key (address) 


The sort is performed the same way: 
& “ARYSORT", AS(1,0) TO AS(3,0) ON KEY%(0) 


PARTIAL ARRAY SORTING: It is possible to sort part of 
an array without altering the other records in the array. 
This means that in a large file of (say) 1,000 records, 
it is possible to sort records #131 to #345 (inclusive) 
without disturbing records 1 to 130 and 346 to 1000: 


& “ARYSORT”, A$(131,0) TO A$(345,0) ON KEY%(0O) 


Note that partial array sorting sorts on COMPLETE 
fields. It is not possible to sort on a “substring” or 
part of a field. 


DESCENDING SORTS: If you would like Mr. ZZZZZ_stto 
appear before Ms. RRRR, simply use a negative key field 
number: 


KEY4(0) = 3 <--Number of keys 
KEYZ(1) = 6 <--Primary key (zip code) 
KEY%4(2) = -2 <--Secondary key (last name) 


Note that the above example will cause the array to 
sorted in ASCENDING zip code order (i.e., from 00000 to 
99999) but people with the same zip code will be sorted 
in DESCENDING order (i.e., from ZZZZZZZ to AAAAAAA). The 
independence of the ascending/descending option of key 
fields makes ARRAY SORT.TB a very powerful command. 


STRING SORTING NUMBERS: If array A$ contains the 
following strings: 


"2S! gy Ey MOO 2" 5. 3. “MS eT” 
We could sort it in the usual way: 
KEY4(0)=1 : KEY4(1)=1 
& "“ARYSORT", AS$(1,0) TO AS$(7,0) ON KEY%(0) 
But the results would be a little strange: 


Rs GM A G1 
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The array is sorted this way, because the elements 
are not seen as numbers, but rather as_ separate 
characters. A correct sort can, however, be forced by 
adding 128 to the sort key number: 


KEY%(0)=1 =: KEY%(1)=1+128 
& “ARYSORT", AS(1,0) TO A$(7,0) ON KEY%Z(0) 
Results: 
"re oma") "3", "5", "7", "23", "50" 


Correspondingly, a descending string numeric sort can 
be forced by subtracting 128 from the sort key number: 


KEY%(0)=1 : KEY%(1)=-1-128 
& “ARYSORT", AS(1,0) TO A$(7,0) ON KEY%(0) 


Results: 


SAMPLE PROGRAM: 


1 CALL PEEK(175)+256*PEEK(176)-46 
2 DIM AS$(3,3), KEY%(2) 
3 . 


100 A$(1,1)="BILL” 
110 AS(1,2)="PARKER” 
120 A$(1,3)="801 W. MARKET ST." 


130 A$(1,4)="SAN DIEGO" 
140 AS(1,5)="CA" 
150 AS(1,6)="92101" 


170 A$(2,1)="NANCY" 

180 AS$(2,2)="ADAMS” 

190 A$(2,3)="BOX 82761" 
200 AS(2,4)="SAN DIEGO" 
210 AS(2,5)="CA" 

220 A$(2,6)="92101" 


240 AS(3,1)="NATTY” 

250 AS(3,2)="DREAD" 

260 AS(3,3)="300 SEA LN" 
270 A$(3,4)="SCOTTSDALE” 
280 AS$(3,5)="AZ" 

290 AS(3,6)="83821" 

300 : 
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310 KEY%(0)=2 : KEY%(1)=6 : KEY%(2)=2 
320 : 

330 & “ARYSORT", AS$(1,0) TO AS$(3,0) ON KEY%(0) 
340 : 

350 FOR I=1 TO 3 

360 : PRINT AS(I,1);" “;AS$(1,2) 

370 : PRINT AS(I,3) 

380 : PRINT AS(1,4);" “3AS(I,5);" ";AS(1,6) 
390 NEXT IL 


Results of sample program (note zip code order): 


NATTY DREAD 
300 SEA LN 
SCOTTSDALE, AZ 83821 


ADAM HARRIS 
BOX 82761 
SAN DIEGO, CA 92101 


MILO MINDERBINDER 
826 W. MARKET ST. 
SAN DIEGO, CA 92101 


NUMERIC ARRAY SORTING 


ARRAY SORT.TB allows for sorting real or integer 
arrays as well as strings. All of the rules given for 
string array sorts apply to numeric sorts except one: 
string sorting of numbers. This is so because the 
command automatically performs a numeric sort on 
numerical arrays. Hence it is NOT required to add 128 to 
the keysort number as with string arrays. 


The following two lines illustrate the use of a numeric 
array: 


10 DIM KEY4(1): KEY%(0)=L: KEY4(1)=1 
20 &ARYSORT",X(1,0) TO X(100,0) ON KEY%(0) 
30 &"ARYSORT",24(1,0) TO Z4(500,0) ON KEY%(0) 


ONE DIMENSIONAL ARRAY SORTING 


To round out its many abilities ARRAY SORT.TB 
provides for sorting one dimensional string, real and 
integer arrays. All of the rules given previously apply 
to one dimensional arrays as well. Note however that the 
number of sort keys specified in KEY%(0) MUST be equal to 
one (1). Therefore, KEY%(1) can only have values of 1, 


31 


129, -l and -129 (normal sort, string sorting numbers, 
descending sort and descending string sorting numbers 


respectively). 


The following program lines illustrate single dimensional 


array sorting: 


10 DIM KEY%(1): KEY%(0)=1: KEY%(1)=1 

20 &"ARYSORT”,AS(1) TO AS(J) ON KEY%(0): 
REM ASCENDING STRING ARRAY SORT: 1 DIMENSIONAL 

30 KEY%(1) = -1: &"ARYSORT",BS(1) TO BS(J) ON KEY%(0): 
REM DESCENDING STRING NUMERIC SORT: 1 DIMENSIONAL 


ERROR CONDITIONS AND THEIR CAUSES: 


TYPE MISMATCH ERROR: 
-The second array type is different from the first 
-The key field array is not an integer array 


ILLEGAL QUANTITY ERROR: 
-Key array is not one dimensional 
-Second subscript doesn“t evaluate to zero 
-Key array subscript does not evaluate to zero 
-Sort beginning or ending elements exceed array 


dimensions 
-Sort ending element is greater than beginning 
element 
-Key array has more elements than the array to be 
sorted 


-Too many key fields specified 


BAD SUBSCRIPT ERROR: 
-Key array contains an illegal field number 


OUT OF DATA ERROR: 
-Array to be sorted was not DIMensioned 
-Second array name is not the same as first array 
name 
-The key aray is not dimensioned 


LIMITATIONS: The command should not be _ used with a 
simulated 1 dimensional array, i.e. DIM A$(50,0) then 


& "SORT" AS(1,0) TO A$(50,0) ON KEY%(0). 
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>> DELIMITED STRINGS.TB << 
by Steve Cochard 


FUNCTION: This command is a package of interrelated 
subcommands that allow a one-dimensional string array to 
be manipulated in a record/field format similar to what 
can be done with a two-dimensional array. Commands are 
included to find a field, replace a field, search the 
entire array for a specified string and sort either part 
of or the entire array on any field. 


SYNTAX: FIND:& “NAME”, "“F[IND]", array svar, var 

svar [, [avar], avar] 

SEARCH: & “NAME”, "“SE[ARCH]",array svar [ TO 
array svar] ,avar, svar 

SORT: & “NAME”, “SO[RT]", array svar [ TO array 
svar] ,avar 

REPLACE: &"NAME", “R[EPLACE]", array svar, avar, 
sexp 


SAMPLE: & “DSTR","“FIND", A$(1),F,A$,S,L 
& “DSTR","F",AS(X+2),F,AS,,L 


& “DSTR","SEARCH",AS(1),F, AS 
& “DSTR","SE",AS(L) TO A$(50),F,AS 


& "DSTR", "SORT" ,AS(1),F 
& "DSTR","SOR",AS(10) TO AS(55),F 


& “DSTR", “REPLACE” ,AS(1),F,A$ 
& “DSTR","R",AS(I+1),3, "SMITH" 


Where (for “FIND"): AS(1l) is the array “record” 
containing the field to be found. F is the field to 
FIND, A$ will return equal to the string contained in the 
specified field, S is the position in the string of the 
start of the field, and L is’ the length of the field in 
the string. 


Where (for "“SEARCH"): AS(I) is the array to 
search and I is the starting element (the array subscript 
must be a variable since the element containing the 
search string is returned in it). F is the field to 
search, A$ is the string to search for. 


Where (for “SORT”"): A$(1) is the array to sort, F 


is the key field to sort on, A$(55) is the last element 
to be sorted. 
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Where (for “REPLACE” ): AS(1) is the record 
containing the fields, F is the field to be replaced, A$ 
is the replacement string. 


HOW TO USE: The first order of business is to define 
a delimited string as a single string within an array 
that is composed of related substrings separated by 
unique delimiting characters. Each of the substrings, 
when taken as a whole, comprise one record. 


An example will help clarify the above. Suppose the 
main program is our now famous mailing list program. We 
need to keep first names, last names, street address, 
city, state, zip and any comments. Normally, this data 
structure would demand the use of a two-dimensional array 
dimensioned N by 7, where N is the number of records and 
7 is the number of fields within the record (a field is a 
“last name", “city”, "state", etc). 


This command will allow the use of a one-dimensional 
array and add powerful search and sort capabilities as 
well. Let”s look at how a sample string would appear for 
our mailing list. The following statement will assign a 
record to AS$(15): 


10 AS(15)="/JOE/SMITH/717 9TH ST./JONESTOWN/PA/19999/" 


Looking at the above statement, the concepts of 
record, field and delimiter should become evident. The 
delimiter in our example is the slash (/), the delimiter 
is always the first character in the string. Its purpose 
is to separate (or delimit) the individual fields within 
the record string. 


Any character may be used as_ the delimiter in the 
record, but it should be a character that will never 
appear in the data within the record, and remember, the 
command will automatically use the first character of the 
string as the delimiter. Consider the following: 


100 A$(15)=".JOE.SMITH.717 9TH ST. .JONESTOWN.PA..19999." 


If a period is used as_ the delimiter, the commands 
will think that the city field is blank, Jonestown is the 
state, PA. is the zip, and 19999 is a comment. The 
entire process is out of whack, due to the fact that 
“street” was abbreviated "“ST."! The problem is easily 
avoided by proper selection of the delimiter. 
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Using Applesoft to do the things that this command 
will do would require quite complex code. Dealing with 
the individual fields would be easier with a_ two 
dimensional array (assuming Delimited Strings.-TB wasnt 
available). That is why most programs use_ two 
dimensional arrays. You“1l now find out why youll never 
need more than one dimension in your arrays. 


>> FIND << 


This command will extract the specified field within 
a string “record”. Using our original example, the fol- 
lowing will “get" the “last name”: 


20 F = 2 : REM FIELD 2 IS THE “NAME” FIELD 
30 & “DSTR","FIND",AS(14),F,NS : REM GET “NAME” IN NS 
40 PRINT “LAST NAME: “";NS 


As can be seen from this example, it is very simple 
to extract a field from a delimited string using this 
command. 


If it is desired to find the location within the 
string of a field, all one has to do is add another 
variable to the command. The following will return the 
“name” in NS$ and the position of the “name” field in the 
variable S: 


10 & “DSTR","FIND",AS(15),F,NS,S 


S returns with the location of the start of the “name” 
within the string A$(15). In our example, NS$ would 
return equal to "SMITH", and S would be equal to 6. 


If it is also desired to know the length of the 
field, another variable may be added to the command: 


10 & “DSTR","FIND",AS$(15),F,NS,S,L 


In this case, L would return the length of the field, 
which would be 5 for our example. Note that it is 
possible to eliminate the S variable, if desired, by 
substituting a comma. The following line would return 
only the string value of the field and the length: 


10 & "DSTR",”"FIND",A$(15),F,NS,,L 
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>> REPLACE << 


This command will replace any specified field with 
another string. 


10 & “DSTR",”REPLACE™,AS(1),F,"MAIN STREET" 


This line will replace the contents of field number F 
within record A$(1) with the string “MAIN STREET”. 


If it is required to clear a field (length of field = 
0) then simply use replace with a null string as_ the 
replacement string, as shown below: 


10 & “DSTR",”REPLACE”,AS$(1),F,”" 


It is also possible to replace a null field with a 
string. This would occur if a field was not known when 
the complete record was entered into our mailing list. 
When the record is later updated, REPLACE will add the 
field for us. 


>> SEARCH << 


This command will search the specified field of the 
array for a string. If there were 500 entries in our 
mailing list, and we needed to find a zip code of 19843, 
then the following would do the trick: 


10 & “DSTR", "SEARCH" ,A$(1) TO A$(500),6,°19843" 
Of course, the following would also work equally as well: 


10 F = 6: Z$ = "19843" : I=1 
20 & “"DSTR","SE",A$(I),F,Z$ 


In the second example, line 20 would search the 
entire array, looking only at the specified field (the 
zip code field) and stopping when it found 19843. Note 
that the array subscript is a variable and not a constant 
in this example. This is required with SEARCH for the 
following reason: 


When a search is completed, the array subscript 
variable ("I" in our case) is set equal to the array 
element containing the "found" string. 


In the previous examples, it would be returned in the 
variable I, and A$(I) would be the desired record. This 
means that the following lines, will print the requested 


record: 
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10 F=6:Z$="19843":1=1 

20 &"DSTR", "SEARCH" ,AS$(1),F,Z$:REM SEARCH FOR ZIP=19843 
30 PRINT AS(I) : REM PRINT FORMATTED STRING 

40 FOR J = 1 TO 7 : REM PRINT THE RECORD 

50 & “DSTR”,"FIND",AS(I),J,A$ : PRINT AS 

60 NEXT 


These lines would print out the record containing the 
zip code 19853. If the next record containing that zip 
were desired, simply increment I by one and do _ another 
search. 


Note: If a search is not successful, the array subscript 
will be changed to 0. The following statement will check 
for that condition: 


70 & “DSTR”,"SEARCH",AS(I) TO A$(50),F,AS 
80 IF I= 0 THEN PRINT “NOT FOUND" 


>> SORT << 


This command will sort the array using the specified 
field as the sort key. If it is desired to sort on 
multiple fields, just sort on them in increasing order of 
importance. For instance, to sort by first and last name 
such that Al Jones was before Bill Jones just do the 
following: 


50 & “DSTR",”SORT",A$(1),1: REM SORT ON FIRST NAME 
60 & “DSTR","SORT",AS(1),2: REM NOW LAST NAMES 


This will sort the array such that all similar last 
names are together and the first names of all people with 
common last names are also in order. Note that it is 
possible to specify sorts as “deep” as required. 


Note: strings elements of zero length will sort to the 
top of the array (i.e. they are considered to be “less 
than” non-zero length strings.) If this becomes’ a 
problem you should specify a subrange to sort that only 
contains non-zero length strings. 


LIMITATIONS: Multi-dimensional arrays may not be used 
with this command. This command MUST be used with the 
Toolbox system, it WILL NOT work otherwise. 


ERRORS: STRING TOO LONG error will occur if the 


string resulting from a REPLACE is longer than 255 
characters. 
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>> ARRAY RENAME.TB << 


by Steve Cochard 


FUNCTION: This command will rename an existing array- 


SYNTAX: & “NAME”, array varl, array var2 [,array 
varl, array var2] 


SAMPLE: & “ARRAY RENAME” ,XY(0),A(O) 
& “ARRAY RENAME” ,AS(0),B1$(0),C%(0) ,Q%(0) 


HOW TO USE: This command comes in handy for a number 
of applications that may not be readily apparent. The 
transfer of data from one array to another may be 
accomplished very rapidly using ARRAY RENAME. This 
simple Applesoft program illustrates the technique: 


10 DIM A(100,100),B( 100,100) 
20 FOR I = 1 TO 100: FOR J = 1 TO 100 
30 READ A(I,J),B(I,J) 
40 NEXT J,I 
50 . 
- (processing takes place) 


100 REM SWAP ALL 20,000 ARRAY ELEMENTS 

110 &”ARRAY RENAME” ,A(O),T(0):REM T = TEMP DUMMY NAME 
120 &"ARRAY RENAME" ,B(0),A(0):REM B BECOMES A 

130 &"ARRAY RENAME” ,T(0),A(0):REM T BECOMES B 

140 REM ALL DONE 


Note that the array "T" does not have to be DIMen- 
sioned since it is a dummy array and only temporarily 
takes on the identity of array "A". After line 110 is 
executed, no array by the name of “A” exists, only “T" 
and "B". This example illustrates one advantage, speed. 


Another use of ARRAY RENAME.TB is for programmers who 
keep an Applesoft subroutine library on disk. Consider 
the following: 


Applesoft subroutines can only work on arrays that 
are specified in the subroutine. Therefore, it is not 
possible to write a truly general purpose’ subroutine 
that operates on arrays in Applesoft. Using Array 
Rename.TB you can write a subroutine using an array 
named "AR", for example. When you need to pass an array 
named “BE” just change it to “AR” using this command, go 
to the subroutine, and change its name back to “BE” when 
your done (when the subroutine returns). 
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Note that the subscripts used with this command are dummy 
subscripts. 


LIMITATIONS: This command cannot be used to _ change 
array types, i.e. & “ARRAY RENAME”,A(O),BS(0) is an 
illegal form of the command and will result in an error. 


ERRORS: OUT OF DATA ERROR will occur if the “old” 
array has not been previously DIMensioned. This could 
occur if the array was not DIMensioned or if its name 
had been previously changed. TYPE MISMATCH ERROR will 
occur if the array types specified in the command do not 
match. Only array names of the same type may be 
specified. You are allowed to rename more than one type 
of array in a single statement, however. For example: 


& “ARRAY RENAME” ,A(0),B(0),C$(0),CATS(O) (legal) 
& “ARRAY RENAME”,A(0),CS(0),B(0),CATS(0) (illegal) 


>> ARRAY CLEAR.TB << 
by Steve Cochard 


FUNCTION:This command is a simple time saving device 
that clears a specified array almost instantly. It does 
not delete the array from memory, but rather, “zeroes” 
the elements within it. 


SYNTAX: & "NAME" , array var [{,array var}] 


SAMPLE: & “CLEAR” ,A$(0) 
& “CLEAR” ,DE(O),X(0),1%(0),AS(0) 


HOW TO USE IT: A real time saver for large multi- 
dimensional arrays when they must be cleared. Instead of 
multiple FOR-NEXT loops this one simple command will do 
it. 


The command works in immediate or deferred execution. 
the command works with floating point, integer or string 
arrays. 


The subscripts used with the arrays in this command 
are dummy subscripts. 


ERRORS: OUT OF DATA error will occur if the array 
specified does not exist in memory (array not previously 
dimensioned). 
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SAMPLE LISTING: 


100 DIM A(40,40),B$(10): & “ARRAY CLEAR”,A(0),B$(0) 
110 DIM C%(30): & "ARRAY CLEAR" ,C%(0) 
120 END 


TECHNICAL NOTE: If a large string array is cleared 
using this command it is a good idea to use GARBAGE 
MAN.TB immediately. This will free additional memory 
that was being used to hold the strings. This is not 
required for real or integer arrays. 


>> ARRAY DELETE.TB << 
by Steve Cochard 


FUNCTION: Will delete an existing array completely from 
memory. 


SYNTAX: & "NAME", array var[{,array var}] 


SAMPLE: & “ARRAY DELETE”, A(0) 
& "ARRAY DELETE”, C$(0),1IP%(0),XY(0) 


HOW TO USE IT: This command may be used to free up 
memory when an array is no longer required or when a 
larger or smaller array is required and the data residing 
in the current array is not needed. 


Note that the subscripts used with this command are 
dummy subscripts. 


ERROR MESSAGE: An OUT OF DATA error will occur if the 
array(s) specified in the command was not found (array 
not previously DIMensioned). 


SAMPLE LISTING: 


100 FOR I = 1 TO 100 

110 PRINT A$(1I),B(1) : REM PRINT SOME RESULTS 

120 NEXT 

130 & “ARRAY DELETE”, A$(0),B(0) : REM NO NEED FOR THESE 
140 END 


TECHNICAL NOTE: If a large string array is deleted 
using this command, it is a good idea to use GARBAGE 
MAN.TB immediately. This will free additional memory 
that was being used to hold the strings. 
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>> ARRAY REDIM.TB << 
by Steve Cochard 


FUNCTION: This command allows a previously dimensioned 
array to be redimensioned WITHOUT any loss of data. The 
command will work with integer, string and real arrays. 
It will redimension one and two-dimensional arrays only. 


SYNTAX: & “NAME”, array name(aexp,aexp) 


SAMPLE: & "REDIM",A(10) 

& "REDIM",AS$(10,10) 
& “REDIM",X%(A, 10) 
& 


“REDIM",A(5,C%(3)) 


HOW TO USE: This command will redimension any type of 
array without loss of data. It is used in the same 
Manner as an Applesoft DIM statement. The subscripts 
specified in the command may be any arithmetic variable, 
constant or expression (real or integer). 


This command should be used whenever it is deter- 
mined, by a running Applesoft program, that a larger or 
smaller array is required. It could be used in an error 
handling routine that deals with BAD SUBSCRIPT errors. 
If such an error is encountered, the array in question is 
simply redimensioned to a larger size and control is 
returned to the point where the error occured. 


LIMITATIONS: This command will not work with arrays 
that have more than two dimensions. This command will 
not convert one-dimensional arrays to two, nor two to 
one. 


ERRORS: OUT OF DATA ERROR will occur if the desired 
array has not been previously dimensioned. A BAD 
SUBSCRIPT error will occur if a one-dimensional array is 
to be redimensioned to a two-dimensional array or vice 
versa. This error will also result if an array of more 
than two dimensions is used. 
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>> ARRAY TRANSFER.TB << 
by Steve Cochard 


FUNCTION: This command will transfer a selected range 
of data from one array to another. It will work with 
string, integer or real arrays. 


SYNTAX: & “NAME”, array (subscriptl) TO array 
(subscript2) , array2 
&"NAME", start of source TO end of source, 
destination array 


SAMPLE: & "TRANSFER", NAS$(1) TO NAS$(100), BS(1) 

& “TRANSFER”, C$(1,1) TO C$(100,1), AS(1) 
& “TRANSFER”, CS(1,4) TO CS$(100,4), A$(1,5) 
& “TRANSFER”, CS$(1,4) TO C$(100,4), AS(1,5) 
& "TRANSFER", AS(1) TO AS$(100), C$(100,1) 


HOW TO USE IT: This command comes in handy for the 
rapid transfer of data from one array to another. You 
simply specify the starting element of the source array, 
the ending element of the source array and finaly the 
starting element of the destination array. This command 
will eliminate a FOR-NEXT loop, speed up the transfer of 
the data and, for string arrays, eliminate the creation 
of string garbage. 


One application of Array Transfer is with Delimited 
Strings. If a two dimensional string array contains one 
column of elements that are delimited strings, the entire 
column can _ be transferred to a single dimensioned array 
to use with the Delimited String command. (Remember, the 
Delimited String command only works with single dimension 
arrays, for internal reasons.) Using this technique of 
delimited strings within a two dimensional string array 
will yield the ability to store multiple sets of data 
within one element of an array. If all of the elements 
of the two dimensional array contained delimited strings, 
the net effect would be a three dimension array! 
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Let“~s look at a short example, first of a simple 
transfer, then of the use with a delimited string: 


10 DIM A$(10),B$(10): REM DIM ARRAYS 
20 FOR I = 1 TO 10: READ A$(1): NEXT: REM GET DATA 
30 &"TRANSFER”, AS(1) TO A$(10), B$(1): REM COPY AS 


- do some processing on A$() 


60 & “TRANSFER”, BS(1) TO BS$(10), AS(1) 
70 REM RESTORE STRINGS BACK INTO AS() FOR FUN! 


The second example will show how to use this command 
with the Delimited String command. First lets define a 
data structure for the two dimensional array: 


A$(n,1)= column is names of friends 
AS(n,2)= addresses of friends 
A$(n,3)= phone numbers of friends 
AS(n,4)= names of children of friends 
AS(n,5)= names of wives of friends 
AS(n,6)= birthdays of friend & family 


If you closely study the data structure for the AS$() 
array shown above, you will notice something a bit 
unusual. The fourth and sixth columns of data in the 
table (array) contain more than one piece of data! 


Normally only one piece of data is allowed per 
element in an array, but when you use Delimited Strings 
you can define as many fields within a single array 
element as you need. Now let~s look at some sample data: 


AS(1,1) = "HOWARD BEALE" 
AS(1,2) = "717 TRESEDER ST" 

AS(1,3) = "215-555-1212" 

AS(1,4) = "/JOEY/MIKE/CINDY/” 

AS(1,5) = “DONNA” 

AS(1,6) = "/JANS/FEB14/NOV23/MAY9/JUN14/" 


The first, second, third and fifth elements of the 
array look normal. The fourth and sixth each have 
multiple entries; childrens names and families birthdays. 
These elements are known as Delimited Strings (they are 
strings delimited by the "/"). The Delimited String.TB 
command in the Database Toolbox will allow processing 
these types of strings very easily. But how does all 
this tie into Array Transfer? 
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Simple, DELIMITED STRINGS.TB cannot work with two 
dimensional arrays. But by using Array Transfer you can 
store a column of delimited strings in a two dimensional 
array and when they need to be processed, simply transfer 
them to a single dimension array. When processing is 
completed transfer them back again. This simple tech- 
nique should open up _ some very interesting possiblities 
in your programs. The sample data structure above is 
just one possibility. How many times have you tried to 
implement such a data structure, only to find Applesoft 
fighting you all the way? 


ERRORS: BAD SUBSCRIPT will occur it the start and 
ending arrays are not the same name. It will also occur 
if the source and destination arrays are the same. 


IMPORTANT NOTE: Due to the way Applesoft stores data 
internally for arrays, you cannot transfer rows of data 
to another array. For example, you would expect’ the 
following statement: 


10 &"TRANSFER", A$(1,1) TO AS$(1,10), BS(1) 
to transfer the following elements to BS$(1).-.B$(10) 
AS(1,1), A$(1,2), AS(1,3)---A$(1,10) 


This will not work!! What will happen is that the 
command will transfer as follows: 


AS(1,1),A$(2,1),A$(3,1)---A$(10,1),A$(1,2)--AS(2,2)--- 
- -AS(3,2).-AS(10,2),A$(1,3)-------A$(1,10) 


The simplest way to visualize this is to make a table 
with graph paper and "X" out each box in 9 columns and 
then the first box in the 10th column. It would be 
expected to work by "Xing out only the top row, but 
alas...Applesoft again. 


Note that this “error” is not checked for since some 
programmers may want this “feature” to work. Since it is 
not checked: 


IT MAY BE POSSIBLE TO DESTROY DATA IN MEMORY IF THE 
TARGET ARRAY IS NOT LARGE ENOUGH TO HOLD ALL OF THE DATA 
THAT IS TRANSFERED! 
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>> ARRAY ROW COL ADD.TB << 
>> ARRAY ROW COL KILL.TB << 


by Steve Cochard 


FUNCTION: These commands will add or delete any 
specified row or column in a _ two-dimensional real, 
integer or string array. 


SYNTAX: & “NAME”, array name ( avar , avar ) 


SAMPLE: & “ARRAY ROW COL ADD", A (D,RC) 
& "ARRAY ROW COL KILL", A(D,RC) 


Where A(D,RC) is the array to be manipulated, D is 
the dimension of interest, RC is the row or column of 
that dimension to be added or deleted. 


HOW TO USE: These commands will come in handy when 
dealing with data in the form of records. The data that 
makes up a checkbook record would be stored in a 
two-dimensional string array. When it is required to 
insert a new record into the file in order to keep them 
sorted correctly, or for any other reason, just execute 
the ROW COL ADD command with the correct variables and a 
new space for the new data is opened up. If it is 
desired to delete a record from an in-memory data file, 
just use ROW COL KILL and the record will be eliminated. 


Take special note of the fact that ADDing or KILLing 
a row or column WILL change the dimensions of the array. 
It is important, then, for the program to keep track of 
what the array was dimensioned to originally and how it 
was changed during the course of the program. 


The following shows a brief example of the commands: 


10 DIM A$(200,5) : REM 200 CHECKS WITH 5 DATA FIELDS 


- processing 


100 REM CHECK INSERT ROUTINE 

110 INPUT "INSERT BEFORE WHAT #: “3A 

120 D=l1 :REM ADD TO DIM 1, DIM 1 THEN = 201 

130 RC=A : REM INSERT A NEW RECORD ~A“ 

140 & "ARRAY ROW COL ADD", A$(D,RC):REM ALL DONE! 
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(example program continued...) 
- processing 


200 REM DELETE A CHECK ROUTINE 

210 INPUT “DELETE WHICH CHECK #: "3A 

220 D=1: REM DELETE A RECORD, DIM1=DIM1-1 

230 RC=A : REM DELETE RECORD # A 

240 & “ARRAY ROW COL KILL”,AS$(D,RC): REM ALL DONE! 


The above simple examples illustrate the simplicity 
of adding or deleting data in an array using these 
commands. Consider’ the alternative using Applesoft 
loops: 


10 DIM A$(200,5): MAXD = 200 
100 REM INSERT A CHECK ROUTINE 
110 INPUT “INSERT BEFORE WHAT CHECK #: "3A 
120 FOR I=MAXD TO A STEP -1l 
130 FOR J=0 TO 5 
140 AS(1,J)=AS(I-1,J) 

150 NEXT J 
160 NEXT I 
170 FOR I=0 TO 5 
180 AS(A,I)="" 

190 NEXT I 


This example illustrates the code required to do an 
insert in Applesoft. The two major points of interest 
are the amount of code and time it would take to execute 
the nested loops and secondly the fact that 1200 strings 
would have been moved. Imagine how often the garbage man 
would have to come around if the entire program worked 
like that! Obviously ROW COL ADD and KILL would do the 
job much faster and cleaner. 


One last point. In the Applesoft example the array 
dimensions are fixed. Therefore, if one wanted to insert 
a check into a filled array you would lose the last 
record, a bad situation for your checkbook! 


LIMITATIONS: Note that D and RC must be real vari- 
ables Aexpressions are not allowed in this command; to do 
so would result in a possible destruction of data in the 
data table. 


ERRORS: BAD SUBSCRIPT error will occur if D_ is 
greater than 2 or less than l. It will also occur if RC 
specifies a row or column that is greater than the 
dimension of the array. OUT OF DATA error will occur if 
the array does not exist. 
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>> ARRAY FUNCTIONS.TB << 
>> ARRAY FUNCTIONS SINGLE.TB << 
>> ARRAY RANDOM.TB << 
>> ARRAY FUNCTIONS PARSE.TB << 


by Steve Cochard 


FUNCTION: These utilities are a collection of commands 
that allow any one of over 25 Applesoft functions to be 
performed on every element of an array at once. In 
addition, the ARRAY FUNCTIONS PARSE.TB command allows 
complete expressions to be performed on entire arrays. 


SYNTAX: & “NAME” array avarl= array avar2 aop aexpr 
{functions} 
& "NAME" array avarl= func array avar2 
{functions single} 
& “NAME” array avar = RND (aexp) {rnd} 
& "NAME" array var = expr {functions parse} 
SAMPLE: 
& “FUNCTIONS”, X(0)=X(0)*5 : REM ARRAY FUNCTIONS 
& "FUNCTIONS S", X(0)=SIN (Y¥(0)) : REM ARRAY FTNS SNGLE 
& "RANDOM", X(0)=RND(X(0)) : REM ARRAY RANDOM 
& "PARSE", X(0)=SIN( A(O)+2)*USR(A) / PEEK(B(O) ) 
: REM ARRAY PARSE 


FUNCTIONS AVAILABLE IN THE “ARRAY FUNCTIONS” COMMAND 


Ftn Example 1 Example 2 
ADD: X(0)=X(0)+5 X(0)=¥(0)+5 
SUB: X(0)=X(0)-4 X(0)=¥(0)-4 
MULT: X(0)=X(0)*3  X(0)=¥(0)*3 
DIV: X(0)=X(O)/2 xX(0)=¥(0)/2 
EQU: a X(0)=Y(0) 
PWR: X(0)=X(0)*3 X(0)=¥(0)73 


FUNCTIONS AVAILABLE IN THE “ARRAY FUNCTIONS SINGLE” CMD 


Ftn Example 1 Example 2 

SGN: X(0)=SGN(X(0)) X(0)=SGN(Y(0)) 
USR: X(0)=USR(X(0)) X(0)=USR(Y(0)) 
ABS: X(0)=ABS(X(0)) X(0)=ABS(Y¥(0)) 
PDL: X(0)=PDL(X(0)) X(0)=PDL(Y(0)) 
RND: X(0)=RND(X(0)) X(0)=RND(Y(0)) 
SQR: X(0)=SQR(X(0)) X(0)=SQR(X(0)) 
LOG: X(0)=LOG(X(0)) X(0)=LOG(Y(0)) 
EXP: X(0)=EXP(X(0)) X(0)=EXP(Y(0)) 
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Cos: xX(0)=CoSs(xX(0)) X(0)=COS(Y¥(0)) 
SIN: X(0)=SIN(X(0)) X(0)=SIN(Y(O)) 
TAN: X(O)=TAN(X(O)) X(0O)=TAN(Y(0)) 
ATN: X(O)=ATN(X(0)) X(O)=ATN(Y(O)) 
INT: X(O)=INT(X(0)) X(O)=INT(Y(O)) 
PEEK: X(0)=PEEK(X(0) X(0)=PEEK(Y(0) 


FUNCTIONS AVAILABLE IN THE “ARRAY RANDOM” COMMAND 


Ftn Example 1 
RND: X(0)=RND(0) 
RND: X(0)=RND(1) 
RND: X(0)=RND(-1) 


FUNCTIONS AVAILABLE IN “ARRAY FUNCTIONS PARSE” COMMAND 


Any valid Applesoft expression can be used with an 
array using this function. 


GENERAL USE: All of these commands will operate on 
arrays of any dimension except ARRAY FUNCTIONS PARSE.TB, 
which is limited to single dimension arrays only. The 
sizes of arrayl and array2 must be identical. If they 
are not, a BAD SUBSCRIPT error will result. 


HOW TO USE THE “FUNCTIONS” COMMAND: This command will 
perform the desired arithmetic function on a real array. 
The aexp may be any valid Applesoft expression. As with 
all of the “FUNCTIONS” commands, the main objective is to 
speed up programs and eliminate the use of loops when 
dealing with arrays. 


HOW TO USE THE “FUNCTIONS SINGLE” COMMAND : This 
command will perform any Applesoft arithmetic function on 
every element ina real array. Aside from obvious uses 
(i-e. SIN, COS, ABS, etc.) there are two functions 
available that may not immediately reveal their 
usefulness: USR and PEEK. 

By executing a USR function on an entire array, any 
USR command set up by the user will be executed, essen- 
tially extending ARRAY FUNCTIONS SINGLE.TB to virtually 
any desired function. All of the USR functions included 
in this Library plus any other USR compatible routines 
will work in this manner. 


PEEK offers some interesting possibilites for saving 
pointers and data. If array2 contains the addresses of 
pointers or data of interest, the values contained in 
those pointers will be stored in arrayl. 
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HOW TO USE THE “RANDOM” COMMAND: This command will 
introduce a series of random numbers into the specified 
array. 


Three options are available with this command, all 
specified by the value passed to the command (the one 
between the parentheses): 


If the value is positive, the array elements will 
each have a different random number between O and l. 


If the value is zero, the array elements will all 
have the same random number. 


If the value is negative, a sequence of random 
numbers will be generated, dependent on the magnitude of 
the value. This will allow any of 65,535 different 
random number sequences to be selected. Every time a 
negative value is used, the same sequence is initialized. 
What this means is that every time a -l (for example) is 
used, the exact same random number sequence will be 
returned. 


HOW TO USE THE “PARSE” COMMAND: This command will 
allow an expression of any type to be evaluated with the 
resulting values stored in the specified array. One 
quirk of this command is that it uses, and creates, a 
simple real variable named "Q9". If the main Applesoft 
program uses this variable also, its value will be 
changed by this command. Any valid Applesoft expression, 
containing as many arrays as are needed, may be used. 
The only restrictions are that single dimensional arrays 
must be used and the arrays used in the expression must 
have been dimensioned to a_ size greater than or equal to 
the object array (the one to the left of the equal sign). 


Note that expressions may be included in the array 
subscripts used in the expression on the right of the 
equal sign. However, the first value in the subscript 
expression must be a zero. For example: 


REM TRANSFER EVERY TENTH ELEMENT OF A(0) TO B(0O) 
20 &"PARSE”,B(O0) = A(0O*10):REM EQUIVALENT TO: FOR I= 
1 TO 10: B(1) = A(I*10):NEXT I 
30 REM TRANSFER EVERY TENTH ELEMENT STARTING AT ELEMENT 5 
40 &“PARSE"”,B(0)=A(0*10)+5 
50 REM NEXT STATEMENT IS LIKE 20 BUT WILL ONLY TRANSFER 
ELEMENT 0 OF A(O) TO B(O). 
60 &"PARSE”,B(0)=A(10*0):REM PARSES TO: FOR I=1 TO 10: 
B(L) = A(1*O):NEXT I 
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An easy method to use _ to determine the result of a 
“parse” is to substitute "I" for the “O" in the sub- 
scripts. The imagine the expression being evaluated in a 
FOR-NEXT loop with "I" as the index. 


ERROR MESSAGES: Normal error conditions may be 
encountered if the expression used with ARRAY 
FUNCTIONS-TB or ARRAY FUNCTIONS PARSE.TB is not valid. A 
TYPE MISMATCH ERROR will occur if the object or target 
arrays are not real arrays. An OUT OF DATA ERROR will 
occur if the object or target arrays do not exist in 
memory. 


SAMPLE LISTING: 


10 DIM X(5),Y(5),2(5),Q(50) ,S$(5) ,A$(20) ,B$(15) 
20 FOR I=l TO 5 : LET X(1I)=I : NEXT 
30 &"FUNCTIONS SINGLE”, Y(5)=X(5) 
:REM TRANSFER ELEMENTS OF X TO Y 
40 &"FUNCTIONS SINGLE", X(0)=SGN(Y(0)) 
:REM GET SIGN OF VALUES IN Y INTO X 


50 &"FUNCTIONS", X(0)=X(0)*10 :REM MULTIPLY BY 10 
60 &"FUNCTIONS SINGLE", X(0)=EXP(X(O)) 
70 &"RANDOM", Y(0)=RND(0) 


80 &"PARSE” ,X(0)=5*SIN(Q(0))/VAL (A$(O))*((5*X)+3 123) 
90 &"PARSE”,S$(0)= A$(0)+MID$(BS(0) ,Q(0),2(0) )+".PIC™ 


>> ARRAY STRS$.TB << 
by Steve Cochard 


FUNCTION: This command will convert a real (floating 
point) array into a string array. 


SYNTAX: &"NAME”,array avar [,array svar] 


SAMPLES: &"ARRAY STR$", A(O),BS(Y): REM CONVERT A 
TO BS 
& "ARRAY STRS", A(O) : REM CNVRT INTO STR ARRAY 
(NOTE: A(O) IS RENAMED INTO AS(0)) 


Where: 
A(O) = Source array name 
BS(0) = Destination string array 
Y = Starting element in B$(0) to use 


HOW TO USE: Two options are available with this 
command in order to optimize memory usage. The first 
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option allows an existing string array to be used to 
store the new strings. The second option allows the real 
array to be converted into a string array, thus using 
less memory than the first option. 


Note that dummy subscripts are used with this command. 


LIMITATIONS: If the first option is selected, the 
dimensions of the string array must be large enough to 
hold all the elements of the real array. If multi- 
dimensional arrays are used, the string and real arrays 
preferably should have the same number and size 
dimensions. This is not required, but if the two arrays 
are of different sizes, the command may mix up the 
locations of the elements. 


Note that in option 1, the array B$(0) MUST have been 
defined prior to using the command. A(0O) in this case is 
unaltered. In the second option, A(O) is converted INTO 
A$(0). Thus the array A$(0) need not previously exist, 
although you must also remember then that A(0O) will no 
longer exist after the conversion. 


If the string array is not large enough to hold all 
of the elements of the real array, any arrays physically 
located above the string array in memory will be over— 
written and lost. 


The second option changes the type and name of the 
real array to a string array. For example, if the real 
array name was JOE and the ARRAY STRS function was 
executed, the array would be renamed JOE$. The ARRAY 
RENAME command can then be used to change the name to 
whatever is desired. 


SAMPLE LISTING: 

10 FOR I = 1 TO 10: REM COULD USE ARRAY RND HERE! 
20 :LET A(I) = RND (1) 

30 NEXT 


40 & "ARRAY STRS$",A(O0) :REM NOTE DUMMY SUBSCRIPTS! 
50 FOR I = 1 TO 10: REM COULD USE ARRAY FUNCTIONS! 


60 :LET A$(I) = LEFTS(AS$(1),3):REM NOTE A(O) IS NOW AS$(0) 
70 NEXT 
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>> ARRAY VAL.TB << 
by Steve Cochard 


FUNCTION: This command will attempt to interpret an 
entire string array as real numbers and return those 
values to the specified real array. 


SYNTAX: & “NAME” ,array avar = VAL array svar 
SAMPLE: & “ARRAY VAL", A(O) = VAL (BS(0)) 


Where A(O) is the target real array. The subscripts 
for this array are real subscripts. This implies that 
the converted values may be placed in the real array at 
any desired location. BS$(0) is the object string array. 
The subscripts for this array are dummy subscripts, the 
entire array is evaluated and stored in the target array. 


HOW TO USE: This command would be used in situations 
where the Applesoft VAL command is used. This command 
operates on an entire array at once and saves the time an 
effort required to program an Applesoft equivalent using 
loops. 


LIMITATIONS: The dimensions of the real array must be 
large enough to hold all elements of the string array. 
If multi-dimensioned arrays are used, the string and real 
arrays preferably should have the same number and size 
dimensions. This is not required, but if the two arrays 
are of different sizes, the command may mix up the 
locations of the elements. 


If the real array is not large enough to hold all of 
the elements of the string array then any arrays 
physically located above the real array in memory will be 
overwritten and lost. 


ERROR MESSSAGES: An OUT OF DATA error will occur if 
the object string array does not exist. A TYPE MISMATCH 
error will occur if the object array is not a _ string 
array or if the target array is not a real array. 


SAMPLE LISTING: 


10 FOR I=1 TO 10:BS$(1L)=STRS$(RND(1)):NEXT I 
20 &"ARRAY VAL" ,A(0) = VAL(BS(0)) 
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>> ARRAY ROUNDING.TB << 
by Steve Cochard 
FUNCTION: This command will take any _ real array and 
round every element within it to the number of specified 
decimal places. 
LENGTH: 187 bytes (S$BB) 
SYNTAX: & "NAME",array avar TO aexpr 


SAMPLE: & "“ROUND",Y(O) TO X 


Where aexpr = number of decimal places desired. 
Array avar = a real array to be rounded. Note that array 
subscripts used with this command are dummy subscripts. 


HOW TO USE: This command would be used to round real 
numbers to a specified number of decimal places. One 
good example of its use is to format dollar and cent 
figures. Prior to printing any values that represent 
money, the array would be rounded to two decimal places. 


ERROR MESSAGES: Standard error conditions may be 
encountered if the aexpr is not valid. 


SAMPLE LISTING: 
10 LET PRECISN=2 


20 LET ZZ(1)=1.023 : 22(2)=2.145 : 22(3)=3.1415 
30 & “ROUND",ZZ(0) TO PRECISN 


>> MATRIX IDENTITY.TB << 
by Andy Scheck 
FUNCTION: Returns the identity matrix in the designated 
array. The identity matrix is a constant matrix wherein 
the diagonal consists entirely of “1l°s and all other 
positions are filled with “Os. 
SAMPLE: &"NAME",array var(0,0) 


SAMPLE: &"IDN",A(0,0) 
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HOW TO USE IT: This command clears all of the 
selected square matrix elements to zero, and then sets 
the diagonal elements to “l”. The resultant identity 
matrix is useful for certain matrix operations. Note 
that the array subscripts used with this command are 


dummy subscripts. 

LIMITATIONS: The designated array must be a_ real 
numeric array (integer and string arrays are not allowed) 
and the array must be dimensioned to a “square” array. 
That is, the array must be two-dimensional and both 
dimensions must be equal in size. Example: DIM A(25,25), 
N( 10,10). 


>> MATRIX TRANSPOSE.TB << 
by Andy Scheck 

FUNCTION: Transposes the designated array. 
SYNTAX: &"NAME”,array var(0,0) 
SAMPLE: &"TRN”,A(0,0) 
HOW TO USE IT: This command transposes the designated 
array. This operation converts an M x N array to anN x 
M array. An example is given below: 
Original Array: After &"TRN”,A(0,0): 


y 
2 A=1135 1] 
4 | 6 | 
6 


Wwe 


| 
Let A = | 
| 


Outside of “official” matrix operations, this 
function also operates on string arrays. This can be 
useful for transposing the "record and field" 
relationships within an array. For example, let us 
suppose that you had an Applesoft program with a string 
array dimensioned as follows: 


DIM R$(5,100) 


where “5° represented five fields (such as name, address, 
city, state, zip) within a data file of 100 records. Now 
let us suppose that you would like to reverse the 
situation so that the array would appear as though you 
had dimensioned it with: 

DIM R$(100,5) 
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With one statement, &"TRN",R$(0O,0) this transposition 
will occur. 


LIMITATIONS: The designated array must be either a 
string or real numeric array, and must be dimensioned as 
a two-dimensional array. 


Since this command temporarily allocates, from 
available free memory, an amount equivalent to the size 
of the original array, transposing large arrays may cause 
an "OUT OF MEMORY" error. If this does happen, the 
original array will be left in its original state. 


>> MATRIX MULTIPLY.TB << 
by Andy Scheck 


FUNCTION: Returns the matrix product of two real 
numeric arrays. 


SYNTAX: &"NAME",array var(0,0) = array varl(0,0) * 
array var2(0,0) 


SAMPLE: &"MUL",A(0,0) = B(0,0) * C(0,0) 


HOW TO USE IT: This command returns the matrix 
product of two arrays. The matrix multiply is not a 
simple element by element multiply, but an involved 
mathematical function with specific properties. The 
product of an array and the identity matrix is just the 
original array. 


The matrix multiply is useful for many scientific and 
engineering applications. One area of -.general use is 
computer graphics. The projection of a three-dimensional 
object onto a plane (such as a video screen) can be 
formulated in terms of a matrix multiplication. Matrix 
operations are a detailed study unto themselves, and 
entire textbooks are devoted their description, and their 
specific applications. Thus no attempt is made here to 
explain there specific use. 


LIMITATIONS: The array must be a real numeric array. 
String and integer arrays are not allowed. If array 
array B is dimensioned at M x N, then array C must have N 
rows (i-e. C is dimensioned at N x P). The product of B 
and C in this case would be an M x P array. 
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>> MATRIX INVERSION.TB << 
by Andy Scheck 


FUNCTION: Returns the inverse and the determinant of 
the designated square real array. 


SYNTAX: &"NAME”,array var(0,0),avar 


SAMPLE: &"INV",A(0,0),X ;where X returns the determ. 
&"INV",A(0,0),DET ;where DET returns the determ. 


HOW TO USE IT: The inverse of a matrix is useful in 
many applications including curve fitting, circuit 
analysis, and solving simultaneous equations. 


A non-zero determinant indicates a valid inversion. 
A determinant of zero indicates tha the array is singular 
(has no inverse), and the resulting array data is 
essentially garbage as the inversion is done “in place”. 
Note that all array indexing begins at element zero. 
Failure to make use of the zero position in rows and 
columns will lead to singular results. 


The command is more than five times faster than the 
same routine written entirely in Applesoft BASIC. 


LIMITATIONS: A very small amount of available memory 
is allocated by the inversion command for pointers. This 
may cause an “OUT OF MEMORY” error in extremely large 
programs, however, the original data array will be left 
intact. 


To avoid this, try doing a FRE(O) immediately before 
the inversion. 

The designated array must be a real numeric array 
(integer and string arrays are not allowed) and the array 
must be dimensioned to a “square” array. That is, the 
array must be two-dimensional and both dimensions must be 
equal in size. Example: DIM A(25,25), N(10,10). 


>> USR MACHINE.TB << 
by Steve Cochard 
FUNCTION: This command is a utility routine to be used 
in conjunction with both the TOOLBOX SYSTEM and with USR 


compatible machine language routines, such as the USR 
commands in the Database Toolbox. It allows for simple 
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interfacing of routines to the Applesoft USR_ function,’ 
similar to using shape tables with Wizard“s Toolbox I. 


SYNTAX: & “NAME”, usr routine name 
& “NAME”, sexpr 


EXAMPLES: 10 & “USR MACHINE”,”“USR ARC COS" 
20 & “USR MACHINE”,"USR RAD DEG" 
30 & "USR MACHINE” ,UFS 


HOW TO USE: This command will allow the use of 
multiple USR functions within a program. Similar to the 
Toolbox system and it”s interface with the ampersand (&), 
this command allows the programmer to specify the names 
of all USR functions and then link them to the Applesoft 
USR command for later use. 


To use USR MACHINE it is first necessary to add the 
desired commands (which must be compatible with the USR 
function) to the Applesoft program. Take special note 
that the USR MACHINE will not operate without the 
commands having been added by the Workbench. The next 
step is to append USR MACHINE itself to the Applesoft 
program with the Workbench. After this is done all of 
the power of USR is available. 


To select a command to be linked to USR the USR 
MACHINE is executed, using the syntax outlined above, 
with the name of the command to be linked to the USR 
function. That*s all there is to it! 


For example, assume that an Applesoft BASIC program 
had appended to it USR ARC COS, USR RAD DEG and USR_ DEG 
RAD, along with USR MACHINE. During the program it was 
desired to do some calculations which used the inverse 
cosine function and then needed to convert the results to 
degrees along with some other calculations. The program, 
then, might appear something like the following: 


10 & "USR MACHINE", "USR ARC COS": REM USR=ARC COS 
20 A = COS( USR(X)+USR (Y)): REM USE THE ARC COS A BIT 
30 A= USR (A) :REM TAKE ARC COS OF RESULT OF LAST CALC 
30 & “USR MACHINE","USR RAD DEG": REM USR= RAD->DEG 
40 A =5* USR(A)+X°2: REM DO SOME CALCS WITH DEGREES 


In the preceeding example a few important points 
appear. First, is how the USR function is defined by USR 
MACHINE. In lines 10 and 30 the USR function is assigned 
to perform the inverse cosine function and then a radian 
to degree conversion function. Notice that the USR 
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function, once defined by USR MACHINE will remain as it 
was defined until it is redefined by USR MACHINE, as is 


the case in line 30. 


The second point is, which is where the true power of 
the USR function lies, the USR function may be used 
anywhere an equivalant Applesoft function could be used. 


ERRORS: UNDEFINED FUNCTION error will result if USR 
MACHINE cannot find the specified command. 


>> USR FUNCTIONS << 
by Steve Cochard 


FUNCTION: These commands interface with the USR 
function of Applesoft to add the functions listed below 


to Applesoft. 


SYNTAX: The normal Applesoft USR syntax is used to 
execute any of these functions. 


SAMPLE: X = USR (At5/3)%*3.14159 


HOW TO USE: These commands are executed using not the 
Ampersand but with the Applesoft USR function. This 
allows any of these commands to be used in any arithmetic 
expression in the exact same fashion as any normal 
Applesoft function. The syntax of the USR function is 
given in the Applesoft manual but for continuity is 
presented here: 


SYNTAX USR ( AEXPR ) 


Where AEXPR is any valid Applesoft arithmetic 
expression. For example, suppose it was desired to take 
the inverse cosine of A * B(5,5)/ (X * EXP (3))). The 
following Applesoft statement would be valid: 


10 Y = USR (A * B(5,5)/ (X * EXP (3)))) 


If ARC COS were linked to the USR function then the 
inverse cosine of the argument of the USK function would 
be stored in Y. 


Note that any of these functions may be used on 
entire arrays if the the ARRAY FUNCTIONS SINGLE.TB 
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command is used to call the desired USR function. For 
example: 


100 & “USR MACHINE”,”“LOG 10”: 
& “FUNCT SING” ,A(0)=USR(B(O)) 


The above statement will first link LOG 10.TB to the 
USR function and then take the log to the base 10 of each 
element of array B and _ store the results in array A. 


FUNCTIONS PERFORMED BY TOOLBOX USER FUNCTIONS: 


LOG 10: Will return the logarithm to the base 10 of 
the given expression. 


SINH: Will return the hyperbolic sine of the 
given expression. 


COSH: Will return the hyperbolic cosine of the 
given expression. 


SECANT: Will return the secant of the given 
expression, where the expression is given 
an radians. 


ARC COS: Will return the inverse cosine of the 
given expression. The result is returned 
in radians. 


ARC SIN: Will return the inverse sine of the given 
expression. The result is returned in 
radians. 

RAD DEG: Will convert radians to degrees (expression 
given in radians, result returned in 
degrees.) 

DEG RAD: Will convert degrees to radians. 


INVERSE TANH: Will return the inverse hyperbolic tangent 
of the given expression. 


WORD PEEK: Will perform a two byte peek of the memory 
location specified by aexp. This is 
similar to the PTR READ.TB command on the 
Wizard’s Toolbox I disk. The net 
calculation is: 


RESULT = PEEK(aexp) + PEEK(aexptl) * 256 
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>> RND FIX.TB << 
by Steve Cochard 


FUNCTION: This command will seed the Applesoft random 
number generator with the correct value. 


SYNTAX: & “NAME” 
SAMPLE: &"RND FIX" 


HOW TO USE: What? Bugs in Applesoft? This command 
will fix one of the few bugs in Applesoft. It will 
initialize the random number generator seed to the proper 
value. Due to the wrong initialization of a counter 
during the initialization sequence Applesoft executes 
every time it is “cold” started the entire seed is not 
loaded into page zero memory. 


For most applications this will not be a problem. 
But those programs that require a repeatable sequence of 
random numbers will have a _ problem since the seed is 
dependent on truly random events (i-e. what number ended 
up in a certain memory location when the Apple was’ first 
started). 


This command will also come in handy if a program 
wishes to initialize the random number sequence from the 
start again. Since RND FIX re-initializes the seed, the 
sequence of numbers will be initialized also. 


SAMPLE LISTING: 


10 &"RND FIX” : REM INIT RND 

20 FOR I = 1 TO 10 

30 A(1)= RND (1) 

40 PRINT A(1) 

50 NEXT 

60 &"RND FIX" : REM RE-INIT RND 
70 FOR I = 1 TO 10 

80 A(1)= RND (1) 

90 PRINT A(I1) 

100 NEXT 
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>> ONERR.TB << 
by Steve Cochard 


FUNCTION: This command will allow the use of an 
Applesoft ONERR statement to occur anywhere within an 
Applesoft program line. 


SYNTAX: & “NAME”, GOTO line num 
SAMPLE: & ™ ONERR™, GOTO 1000 


HOW TO USE: The Applesoft ONERR GOTO statement allows 
for trapping errors in a program, errors that may not be 
considered “bugs”. This Applesoft command has one little 
quirk that is not present with any other command in the 
language, it skips the remainder of any line of which it 
is a part when it is executed. 


No other command does this, which could lead to 
problems if this “feature” is not remembered whenever 
ONERR is used. (OH! so that”°s why my program has_ been 
bombing out!). When an Applesoft ONERR is encountered 
Applesoft remembers where it was in memory and then 
proceeds to skip the remainder of the line. If there 
were statements in the program line after the ONERR they 
will NOT be executed. 


There is no apparent reason why Applesoft works this 
way; it’s designed to do it but no problems arise if the 
next statement in a line is executed. Use this simple 
command. 


If this command is substituted for Applesoft”s ONERR 
then the ONERR may be used anywhere within a program that 
it is required. It may be used more than once within a 
line also. Let°s look at a sample program to get a 
better idea of the utility of this command: 


10 &"ONERR” ,GOTO 100:PRINT DS"“OPEN"FS: PRINT D$“READ"FS: 
INPUT A: &"ONERR",GOTO 500: FOR I = 1 TO A: INPUT A 
(I): NEXT: &"ONERR",GOTO 100:PRINT D$"CLOSE “: & 
“ONERR", GOTO 1000 
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>> RETURN FIX.TB << 
by Steve Cochard 


FUNCTION: This command will execute the correct code to 
implement an Applesoft RETURN procedure. 


SYNTAX: & “NAME” 
SAMPLE: & “RETURN” 


HOW TO USE: What? Yet another bug in Applesoft? 
This command should be used in place of the Applesoft 
RETURN statement. It is a corrected version of the code 
used to execute that statement. 


If FOR-NEXT loops are used in a subroutine, and it is 
possible to execute a RETURN instruction while still in 
the FOR-NEXT loop then this bug may occur. The result of 
the bug will be an unexpected RETURN WITHOUT GOSUB error. 
This command will avoid the problem by executing the 
correct machine language code to perform the RETURN. 


The following short program will illustrate when the 
problem may arise: 


10 GOSUB 100 

20 END 

100 FOR I = 1 TO 100 

110 IF I = 50 THEN RETURN 
120 NEXT I 

130 RETURN 


This trivial program illustrates the RETURN from 
within a FOR-NEXT loop. When run, the program will go to 
the subroutine located at line 100, execute the loop 
until the value of I reaches 50 and then RETURN to the 
calling program at line 10. 


The bug will arise at random times when the RETURN 
is executed. It may never occur, but then it may just 
happen anytime! 


Since this is the case, it is recommended that 
whenever a program structure such as the one outlined in 
the above example is used, the Applesoft RETURN not be 
used but RETURN FIX.TB be executed instead. Like this: 


110 IF I = 50 THEN & “RETURN FIX" 
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>> GARBAGE MAN.TB << 
by Randy Wiggington and Steve Cochard 


FUNCTION: This command will perform the same function 
as an Applesoft FRE(O), dead string housecleaning. This 
command is many times faster than FRE(0O). 


SYNTAX: &"NAME” [,avarl] [,aexpr] 


Where: Avar is an existing real variable, simple or array 
and aexpr is an algebraic expression. 


SAMPLES: &"GARBAGE” ; This will “clean house", 
always. 


& “GARBAGE” ,A 3 This will “clean house”, always, and 
return the amount of free memory in 
variable A. 


&"GARBAGE” ,A,B 


This will “clean house” only if there are less than B 
bytes of memory free. That is, if B = 2000 and there 
were less than 2000 bytes of free memory left, house 
cleaning would occur. If there were 2000 or more bytes 
of free memory no house cleaning would occur. In either 
case variable A will return the amount of free memory 
remaining in the computer. 


HOW TO USE: Have you ever run your favorite home 
check book program and listed all of the checks you’ve 
written in the last year? Did the screen (or printer) 
suddenly stop printing and the computer seem to_ hang? 
Then, just as suddenly, several minutes later everything 
starts working normally again? If this sounds familiar 
then you HAVE seen the infamous Applesoft garbage man in 
action (inaction?). 


The Database Toolbox has many commands that deal with 
string arrays, adding both power and speed to programs. 
The READER will read them, SORT will sort them, SEARCH 
will search for them, STR$ will create them, but they all 
eventually meet the same fate, Garbage Collection! 
Unless there is a way to overcome the overwhelming delays 
caused by garbage collection, the speed and power 
advantages of the Database Toolbox commands will be 
compromised. 


The GARBAGE MAN.TB command is the answer. This 
command plays a supporting role to all of the other 
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string oriented commands and is valuable not only in 
conjunction with Toolbox commands but also with any 
Applesoft program that makes extensive use of strings and 


string manipulation. 


By executing this command at appropriate places in a 
program the Applesoft garbage collection process will be 
avoided. Some suggestions for use follow: 


1) After deleting a string array with ARRAY DELETE. 
2) Prior to ae string array read using ARRAY READER. 
3) After re-dimensioning a large string array to an array 
with smaller dimensions. 

4) At strategic places in any program, such as prior to 
sections that do a_e significant amount of string 
manipulation (i-e. MIDS, STRS$, LEFTS, RIGHTS, etc.) 
such as main menus, etc. 


Take special note of one difference between Apple- 
soft°s garbage collection routine and GARBAGE MAN.TB. 
Applesoft will perform a garbage collection AUTO- 
MATICALLY; GARBAGE MAN.TB will do it only on demand! 
Therefore, it is the programmer’s responsibility to 
assure that Applesoft never gets its chance to _ house 
clean by on its own, using GARBAGE MAN.TB when and IF it 
is needed. 


The last syntax given above (with an avar and an 
aexpr) will allow the program(mer) to check available 
memory and clean house ONLY if the specified amount of 
memory does not exist. This is in contrast with Apple- 
soft where every time a FRE(O0) is executed house cleaning 
is performed. This unique feature of GARBAGE MAN.TB will 
allow the program to assume responsibility for assuring 
that Applesoft never gets it’s chance to house clean and 
to save even more time if a relatively large amount of 
memory exists and no house cleaning is required. 


ERRORS: TYPE MISMATCH will occur if a string variable 
is used instead of a real or integer variable. You can 
also get an “ILLEGAL QUANTITY ERROR" if the expression 
evaluates to a number less than -65535 or greater’ than 
+65535. 


SAMPLE LISTING: 


5 DIM A$(500,20) 
10 FOR I = 1 TO 500 

20 FOR J = 1 TO 20 

30 AS(1,J)= B$(I,J)+STRS(Y(1))+LEFTS( AS(1,J),5) 
40 NEXT J,1I 
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50 F1=1000: &"GARBAGE”,F,Fl: REM CLEAN IF < 1000 
60 PRINT “FRE MEM="F 

70 &“GARBAGE",F :REM CLEAN AND RETURN FRE IN F 
80 &"GARBAGE” : REM CLEAN HOUSE 


>> DISK START UP.TB << 
by Steve Cochard 


FUNCTION: This command will start the disk drive 
specified in the command. 


SYNTAX: & "NAME" ,aexp,aexp 


SAMPLE: & “DISK START",S,D 
Where: S is any valid aexpr which specifies 
the slot 
D is any valid aexpr which specified 
the drive 


HOW TO USE: This command is meant to supplement the 
disk commands in the Database Toolbox. Extremely fast 
disk access is possible using the commands in the 
Toolbox. These commands push the Disk II to it’s limits. 
Using this command you can_ start the drive before it 
normally would start and save another second or so. 


Note that it is important to use this command about l 
second prior to the actual disk access command that is 
going to be executed. This will allow the disk drive 
time to get up to speed before it is actually used. 


Limitations: This command will not work with ProDOS. 
ERRORS: ILLEGAL QUANTITY error will result if the 
slot is less than O or greater than 7, it will also. 
result if the drive is not 1 or 2 

SAMPLE LISTING: 

10 & “DISK START” ,6,1 

15 REM MISC. PROCESSING HERE 


20 & “READ","R",FS,N,E,AS(1L): REM READ A FILE 
30 END 
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>> FAST FP RUN.TB << 
by Steve Cochard 


FUNCTION: This command will load and RUN an Applesoft 
program at extreme speed. 


SYNTAX: & “NAME”, SEXP 
where SEXP is a string literal,expression or 
variable, SEXP is the program file name 


SAMPLE: & "RUN", “NEXT PROGRAM 
& "RUN", “PROGRAM” + FS 
& "RUN", FS 


HOW TO USE: This is a very simple command to use, 
just execute it! The specified program will be loaded 
and running before you know it! This command should be 
used whenever a_ running Applesoft program RUNs another 
Applesoft program. 


How fast is it? An 8K Applesoft program will be 
loaded and running in 2.4 seconds. 


Suggestion: To load a large program quickly, use a_ short 
“loader” program to load the second and larger main 
program. For example: 


LOADER: 1 CALL PEEK(175) + 256 * PEEK(176) - 46 
10 &"RUN", "MAIN PROGRAM” 


MAIN 1 CALL PEEK(176) + 256 * PEEK(175) —- 46 
PROGRAM: 10 REM MAIN PROGRAM STARTS HERE 


LIMITATIONS: This command only works with standard 
DOS 3.3. It does not work with and is not needed with 
fast DOS°“s such as_ provided on the Database Toolbox 
diskette or relocated DOS“s. It does not work with 
ProDOS. This command cannot be executed in immediate 
execution mode, it must be used from within a running 
Applesoft program. 
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>> FAST BRUN.TB << 
by Steve Cochard 


FUNCTION: This command will BRUN a binary disk file at 
extreme speed. The command will also allow a variable 
list to be added to the commands” syntax to facilitate 
machine language overlays. 


SYNTAX: & "NAME", sexpr [,variables] 


SAMPLE: & “BRUN", “FID” 
“LOWER CASE.TB,3000" 
“BRUN", “ARRAY READER.TB™ + STRS$ (AD), “R", FS, 
R, E, A$(0) 
& “BRUN", “WAIT.TB,3000",5 


m & 
e 
& 
4 


HOW TO USE: The simplest use of FAST BRUN.TB is to 
load and execute a binary (machine language) program from 
within an Applesoft program at extremely high speed. 
This command bloads binary files from disk at 4 times the 
normal speed. How fast? BRUN.TB will load and run a 34 
sector binary file in 2.4 seconds with a Disk J[, 
approximately .75 seconds with a hard disk! 


The command has a few optional syntax’s for the file 
name, as shown above. The simplest file name is a string 
literal, i.e. "FID". 


The file name may, however, be any valid string 
expression such as_ string literal, string variable or 
expression. In order to BRUN a binary program at it’s 
original address, the one from which it is BSAVEd, only 
the file name need be_ specified. This will BLOAD the 
file at its” default address and execute it. 


If it is desired to BRUN the file at some other 
address, the desired address may be specified. The 
method of specifying the address differs from the normal 
DOS BRUN and from BLOAD.TB. The address must be part of 
the string expression which specifies the file name and 
must be separated from the actual file name by a comma 
(i.e. sample syntax for LOWER CASE.TB and ARRAY READER.TB 
above). 


Shown below are a few more samples to illustrate this 
point further: 


& "BRUN", “FILE, 2049" 
& “BRUN", “FILE."+",“+"5000" 
& "BRUN", F$(5)+",6000" 
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& “BRUN", FS(5)+","+STRS$(A) 
& “BRUN", FS(5)+", "+STRS$(PEEK(0)+PEEK(1)*256) 


The desired address must be specified in decimal. If 
the hex address is known, the XNUM.TB command from the 
Wizard~s Toolbox I may be used to convert it to decimal. 


After the file name (and optional address) string 
expression, optional variables may also be included 
depending on the file which is to be BRUN. For example, 
in the third line of the SAMPLES on the previous page, an 
illustration of how the ARRAY READER.TB could be BRUN is 
shown. In this case the variables starting with the 
“R" FS, etc. are the variables usually associated with 
the ARRAY READER-TB module. 


In the fourth example, the WAIT.TB command is’ BRUN, 
and the value "5" is the variable that the WAIT command 
would: normally expect if called in the usual manner. 


For more information on this technique, see Appendix 
C on overlays using the BRUN module. 


LIMITATIONS: This command will only work with 
standard DOS 3.3. It will not work with and is not 
needed with relocated DOS“s, fast DOS“s, such as used on 
the Database Toolbox diskette or with ProDOS. 


>> RESTORE AMPERSAND.TB << 
by Craig Peterson 


FUNCTION: This will restore the ampersand vector to 
its original value, as it was before the Applesoft 


program was run. 
SYNTAX: &"NAME” 
SAMPLE: &"AMP” 


HOW TO USE IT: If you are using any utilities which 
use the ampersand vector, running one of your own 
programs with Toolbox commands in it will re-write that 
vector. When your program’ ends, the previously 
operational utility (if there was one) will no longer 
respond to the ampersand in the immediate mode. 
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To correct this, an optional procedure has been 
provided by way of this command. When your program first 
connects the ampersand vector via the hook-up on line #1, 
the Interface Routine stores the original value of the 
ampersand vector. 


When you are going to END the Applesoft program, 
simply use the RESTORE AMPERSAND.TB command and the 
ampersand will be restored to its earlier function. 


LIMITATIONS: None per se, although a fair degree of 
care is required in its use. If you exit a program via 
an error, Control-C, RESET or any other manner other than 
the controlled (and expected) exit you previously set up, 
it is likely the RESTORE AMPERSAND.TB command will not be 
called. This would then leave the ampersand still 
pointing to the Interface Routine. If you were then to 
re-run your program, the Interface Routine would again 
save the current status of the ampersand, which would now 
point to itself. In other words, any previous ampersand 
related utilities would now be permanently disconnected. 


If you do exit with a RESET or Control-C without the 
RESTORE AMPERSAND.TB function being called, you can still 
restore the ampersand in the immediate mode by just 
typing in: 

&"AMP" {assuming that’s the command name used} 

NOTE: If you understand how the command RESTORE 
AMPERSAND.TB is meant to be used, then it is good 
practice to use it in all programs containing Toolbox 
commands. It MUST, however, be the LAST command used 
before your program ceases execution, since the use of 
this command disables ALL added Toolbox commands. 


If you use RESTORE AMPERSAND.TB, and then try to 
use another command, the result will depend on the 
pre-RUN value of the ampersand vector, but a likely 
result would be a SYNTAX ERROR. 

SAMPLE LISTING: 
1 CALL PEEK(175) + 256 * PEEK(176) - 46 
10 REM USUAL PROGRAM WITH TOOLBOX COMMANDS HERE 


100 &"AMP":END 
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>> BEEP.TB << 
by Craig Peterson 


FUNCTION: Generates a pure tone of a given pitch and 
duration. Can also be used to pause. 


SYNTAX: &"NAME” [,pitch [, duration] ] 
&"NAME” [,aexpr [, aexpr]] 


SAMPLE: &"BEEP" 
&" BEEP" ,P 
&" BEEP” ,P,D 
&" BEEP" ,P+5,D/2 


HOW TO USE IT: The BEEP.TB command can be used in a 
variety of ways. If no variables are included after the 
name, then a tone having about the same pitch and 
duration of the normal Apple beep will be sounded. 


If one variable is included after the command name, 
it will change the pitch of the tone. This variable can 
be any numeric constant, variable or expression, but must 
have a value from O to 255. Lower values cause higher 
pitches. A value of “O” produces no sound. If the pitch 
value is doubled, then a tone about one octave lower will 
be produced. 


If a second variable is given, the length of the tone 
can be changed. The length variable can also be any 
numeric constant, variable or expression having a value 
between O and 255. This length value is determined in 
approximately 1/100°s of a second, so “100° would produce, 
a tone of about one second in length. This allows’ tones 
with lengths ranging from 1/100 to over 2.5 seconds in 
length. 


With pitch set to “O°, the duration can be adjusted 
to produce silent waits of 1/100 to 2.5 seconds. 


LIMITATIONS: Both pitch and duration values must be 
numeric variables in the range of 0-255. 


SAMPLE LISTING: 


1 CALL PEEK(175) + 256 * PEEK(176) - 46 
10 INPUT "PITCH, DURATION?";P,D 

20 &" TONE” ,P,D 

30 GOTO 10 
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Here is a table of the note values produced with 
different values for pitch: 


NOTE PITCH NO. PITCH NO. PITCH NO. 
F SHARP 135 67 33 
F 143 71 35 
E 151 75 37 
E FLAT 160 80 40 
D 170 85 42 
C SHARP 180 90 45 
Cc 191 95 47 
B 202 101 50 
B FLAT 214 107 53 
A 227 113 56 
A FLAT 241 120 60 
G 255 127 63 


AND.. 31 (G) 
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>> TOOLBOX WORKBENCH MAIN MENU << 


The following pages contain further details on each 
of the menu choices presented when running the Workbench 
utility program. They are provided to answer any 
specific questions which might arise about a given menu 
choice. 


MENU OPTION PREREQUISITES 


For each of the options listed in the menu, certain 
conditions must be _ satisfied before the option can be 
selected. The prerequisites for each of the options are 
stated below: 


1 ADD A COMMAND There must be a program in 
memory. 
2 REMOVE A COMMAND At least one command must be 
added. 
3. REMOVE ALL COMMANDS At least one command must be 
added. 
4 COPY ALL ADDED There must be added commands 
COMMANDS TO DISK present. 
5 RESTORE COMMANDS This option can be exercised 
FROM DISK ONLY if no commands are present. 
6 REPORT COMMANDS At least one command must be 
ADDED present. 
7 SEARCH FOR There must be a program in 
COMMANDS memory. 


8 DISPLAY MEMORY MAP There are no prerequisites. 


O EXIT There are no prerequisites. 
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OPTION #1: ADDING COMMANDS 


Although most of the important points regarding this 
Operation have already been covered in the beginning of 
this manual, one more comment is in order regarding this 
option. 


When making up your name for an added command, the 
Name used to call the command can be anything you like, 
subject to the following restrictions: 


a) The maximum length of the command name is fifteen 
characters. 


b) Control characters are not permitted; otherwise 
all keyboard characters other than ~~] and 
quote marks (") are permitted. 


c) The first character must not be a space; 
otherwise spaces within the name are permitted. 


The name used for a command is also independent of 
the name of the Toolbox File used to add the command. 


If you should forget the name you gave a particular 
command, you can always use Option #6 (Command Report) to 
get a report on the command names (and the original file 
names) of all currently added commands. 


OPTION 2: REMOVE A COMMAND 


Suppose you have added 23 commands and then decide 
you really don”t want command #5. The Workbench allows 
you to remove it easily. Select “2° at the menu, and the 
first page of a command report will appear. This chart 
will show all of the added commands, giving both the 
command name, and the name of the Toolbox File from which 
the command was derived. 


The commands are shown eight at atime. If you want 
to go to the next eight, simply press the space bar to 
advance. You can also’ return to the main menu at any 
point by pressing RETURN alone. 


If you see the command you wish to remove, press the 
“R° key to tell the program you wish to remove an item. 
Then enter the number of the command you wish to remove. 


The Workbench will then remove the specified command 
and return you to the main menu. 
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OPTION 3: REMOVE ALL COMMANDS 


It is also possible to remove all added commands at 
one time. Select option #3 for this function. You will 
be asked to confirm your intentions for such a drastic 
action. You must respond with either “Y” or “N° to this 
question. 


SPECIAL NOTE: If you use Apples Renumber program, or 
use use Hi-Res graphics with a program that is too long, 
you may destroy some of the added Toolbox commands. If 
this happens, item #3 in the main menu will change to 
“REMOVE APPENDED MACHINE’ CODE’, meaning that the 
Workbench can no longer recognize the added Toolbox 
commands. See the MEMORY MAP section later and Appendix 
C (A Little More Detail) for more information about this 


situation. 


OPTION #4: COPYING ALL COMMANDS TO DISK 


After using The Workbench for a while, you will 
probably find that there is a certain group of commands 
which you almost always put in your programs. Option 4 
may be used for saving an assembled group of commands to 
disk as a single file. This enables you to add the 
entire group of commands at one time (using Option 5) to 
an Applesoft program in the course of development. 


Such a mini-library can really come in handy when you 
write a variety of different programs. An example of a 
group of commands which could make up a good mini-library 
include: 

a) ARRAY SORT.TB 

b) ARRAY SEARCH.TB 
c) ARRAY REDIM.TB 
d) GARBAGE MAN.TB 


To save a mini-library to disk, select item #4 in 
the main menu of the Workbench. 


The screen will then display: 


ALL ADDED COMMANDS WILL NOW BE 
COPIED TO A FILE ON DISK 


DO YOU WISH TO USE “CMD FILE 
AS THE FILE NAME? [Y] 


If you press “Y° (or just RETURN) here, the 
Workbench will save a copy of all the added commands to 
the diskette under the name “CMD FILE”. 
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If you want to give the file a different name, just 
press “N°” and enter the name of your choice. This is 
the recommended method, so that you don“t accidentally 
overwrite another previously saved mini-library. 


The main purpose for the “CMD FILE” name option is 
for temporary saving of a group of commands. This is 
useful when using the second main application of this 
option, which is to save added commands to disk to enable 
the performance of some operation which might damage 
appended machine code, i-e. added Toolbox commands. 


Although none of Roger Wagner Publishing”s software 
will damage added commands, the same cannot be said for 
all utilities. In particular, APPLE COMPUTER“~S RENUMBER 
program WIPES OUT all commands (or machine code) added to 
an Applesoft program. 


It is not difficult to use Apple Computer”s Renumber 
program to renumber an Applesoft program which has 
Toolbox Files added, but to do so you must first use 
Option #6 to copy all added commands to disk. 


Then use Option #3 to remove all added commands. 
Finally, use Option #5 to restore the commands that you 
saved to disk with Option #6. 


OPTION #5: RESTORING ADDED COMMANDS FROM DISK 


If you have used option #3 to remove added commands 
your program, or if you are just starting a new program, 
to which you wish to add a _ pre-assembled mini-library, 
you may use Option #5 (RESTORE ADDED COMMANDS FROM DISK) 
by following the procedures listed here: 


1) If the Workbench is in memory, re-enter with a CALL 
2051. If the Workbench is not in memory, enter BRUN 
WORKBENCH. 


2) When the menu appears, select Option #5 by pressing 


“5°. You will be asked to confirm by pressing “Y~ (for 
Yes) or RETURN alone. 


3) The program will then display: 


IS THE COMMAND FILE TO BE RESTORED 
CONTAINED IN DISK FILE “CMD FILE“? [Y] 


If you have not used this file name to save _ the 
added commands, enter “N° (for NO). It will then 
display: 
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WHICH FILE NAME THEN? (<RET> = QUIT) 
(FOR CATALOG ENTER “CAT” ) 


You may now either catalog the disk or enter the name 
under which the commands were saved. 


4) The Toolbox will now restore the commands which were 
formerly copied to disk, and return you to the menu. 


If the added commands were originally copied to a 
disk file under the name “CMD FILE”, then the Workbench 
will delete this file from the disk. If you specified 
some other name for the disk file, then it will not be 
deleted. : 


OPTION #6: REPORT COMMANDS ADDED 


The Workbench may be used to add up to 255 commands 
to an Applesoft program. Although it is unlikely you 
will even approach this number, you may from time to time 
wish to see a list of the commands which have been 
added to a particular Applesoft program. 


Pressing “6° at the main menu will produce a Command 
Report. This is useful because it allows you to see what 
commands have already been added and to check on the 
names given to them. 


When selecting each of the “report” options 6 - 8, 
you are asked if output is to go to the printer. If you 
simply want screen display, press RETURN (or “N’). If 
you want a print-out, press “Y°. The Workbench will then 
ask: 


PRINTER IN SLOT: 1 


If this is the correct slot for your printer, press 
RETURN, otherwise enter the slot your printer is in. 


For each command added you are informed of the 
command name and the name of its disk file. 


The Command Report displays eight commands at a time. 
If you have more than eight commands added then press the 
Space bar to go to each successive page (or you can 
return to the menu at any point by pressing RETURN). 


It is also possible to transfer directly from the 
Command Report to the Search option by entering “S”. 
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OPTION #7: SEARCHING FOR TOOLBOX COMMANDS 


This option is provided so that you can list every 
line in your program that uses a Toolbox command. This 
is especially useful when combined with the Command 
Report option. 


The search function has three options: (1) all 
statements in your program using an ampersand (or CALL), 
(2) all Toolbox commands, or (3) use of only a particular 
command. 


To see how the SEARCH option works, follow these 
examples: 


1) From the Workbench, select Option #0 to exit the 
program. Then type in “NEW” to clear memory. 


2) Now enter LOAD POSTMASTER (on the front of the 
Database Toolbox disk). 


3) When the Applesoft prompt returns, enter CALL 2051 
to re-enter the Workbench. 


4) At the menu, select Option #7 and press RETURN. 
The Workbench will then display the following: 


SEARCH TYPE: AMPERSAND STATEMENTS 
DO YOU WISH TO SEARCH FOR: 


1 ALL SUCH STATEMENTS? 
2 ALL TOOLBOX COMMANDS? 
3. A PARTICULAR COMMAND? 


(PRESS “T° TO CHANGE SEARCH TYPE, 
OR <RETURN> TO QUIT) 


5) Select Option #1 to display all of the ampersand 
statements. Since POSTMASTER contains a considerable 
number of ampersand statements it will be necessary 
to press the space bar once or twice to display them 
all (remember only eight are displayed at a time). 
Notice that on each page the Workbench displays: 


PRESS “S” FOR NEW SEARCH 
OR <SPACE> TO CONTINUE 


at the bottom of the screen to prompt you for the 
next page of ampersand statements, as well as to 
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provide you the option of changing the search to 
CALLS instead of AMPERSANDS. 


Since the ampersand is used in the program only to 
call Toolbox commands, and this is the only method 
used to call the commands, you will see the same 
display whether you select option 1 or option 2. 


Normally commands will use the ampersand, but there 
is an alternative method which employs a CALL directly to 
the Toolbox commands themselves. (See Appendix B_ for 
details.) Thus when searching for the Toolbox commands in 
your program you may specify that the search is to be for 
ampersands or for CALLs. (The latter option also allows 
you to search for all CALLs in an Applesoft program 
whether or not they are Toolbox commands.) You can toggle 
between these two options by pressing “T°. 


To see how this works, continue as described here: 

6) Press “S“ to return to the search menu, and press “T~ 
to change to the search for CALLS and repeat’ the 
steps to display the CALLS used in the program. 


Notice the top line of the search menu now appears 
as: 


SEARCH TYPE: CALL STATEMENTS 
When an ampersand or CALL statement is found which 
satisfies the conditions of the search, it is dis- 
played along with the number of the line in which it 
occurs. If the line consists of more than one 
statement, as in the statement below: 


N = INT(VAL(LEFTS$(BS$(J),4))): &”TONE”: FOR I=1 TO N: 
PRINT AS(1);: PRINT " = “A(X(1I)): PRINT: NEXT 


then only the command statement itself will be 
displayed, as in: 


&" TONE” 
SPECIAL NOTES: 


If you are using the CALL method of using Toolbox 
commands, a typical command statement would be: 


CALL IR "NAME", AS, BS 
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You might erroneously omit the “IR” so that your 
program would contain the statement: 


CALL “NAME”, AS, BS 


This would make a nice method of using a command, 
except that it doesn~t work! “NAME” (a string literal) 
cannot be evaluated as a calling address. 


If you use the SEARCH OPTION, and the Workbench finds 
a CALL statement with some expression following the CALL 
which cannot be evaluated as an address, it will display 
the offending statement along with an error message, and 
return you to the immediate mode of Applesoft. This 
gives you the opportunity to correct the CALL (by 
replacing, e-g-, CALL “NAME” with CALL IR “NAME”). You 
can then re-enter the Workbench with the usual CALL 2051 
and resume normal operations. 


OPTION #8: THE MEMORY MAP 


The use of this option is not required for adding or 
removing commands, but does provide useful information 
such as the number of bytes that the added Toolbox 
commands are adding to an Applesoft program. In 
addition, use of this function is highly recommended if 
you are using Hi-Res graphics. 


The Memory Map is selected by choosing Option #8 from 
the main menu of the Workbench. As with previous 
“report” options, you may output the Memory Map to the 
printer by entering a “Y° when the Workbench asks you 
about printer output. 


As noted before, the Workbench occupies memory from 
$800 to $25FF, and when it is present your Applesoft 
program starts at $2601 instead of the usual location of 
$801 (see the diagrams on pp-13-15 of this manual). 


Normally you will be more interested in the location 
of your program at run time, rather than its location 
when the Workbench is present. 


Thus when the Memory Map is first displayed it shows 
the location of your program AS IF it were at $801. 
If you then press “A° the Memory Map will change to 
display the current actual addresses (with your program 
at $2601). You can toggle back and forth between these 
two modes using the “A” key. 
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The Memory Map does not always have the same format. 
It differs according to whether there is a program in 
memory and whether it has any added commands. 


When there is no program in memory, the Memory Map 
displays only four addresses, such as the following: 


PROGRAM START: $0801 = 2049 
LOMEM: $0804 = 2052 
HIMEM: $9600 = 38400 
DOS BUFFERS: $9600 = 38400 


Considerably more information is displayed when there 
is a program in memory. The following is a typical 
Memory Map, corresponding to a situation like that shown 
in Figure 3 on page 15 of this manual. 


APPLE ][ MEMORY MAP 


PROGRAM START: $0801 = 2049 
BASIC PROGRAM END: SOFS5F = 3935 
ACTUAL PROGRAM END: $1289 = 4745 
LOMEM = SIMPLE VARIABLES: $1289 = 4745 
ARRAY SPACE: $12BA = 4794 
ARRAY SPACE ENDS: $12E2 = 4834 
STRINGS: $936E = 37742 
HIMEM = END STRINGS: $9600 = 38400 
DOS BUFFERS: $9600 = 38400 
BASIC PROGRAM LENGTH: $O75E = 1886 
TOOLBOX BYTES ADDED: $032A = 810 
TOTAL PROGRAM LENGTH: $OA88 = 2696 
FREE SPACE: $808C = 32908 
STRING STORAGE: $0292 = 458 
NOTHING UNDER DOS BUFFERS 

MAXFILES = 3 

R MODULE REPORT 


A = ADDRESS TOGGLE, <RETURN> FOR MENU 


The most interesting thing to notice in this chart is 
the entry “TOOLBOX BYTES ADDED" compared to the entry 
“BASIC PROGRAM LENGTH". In the above example, the 
program is 1886 bytes long, while there are 810 bytes of 


machine code appended in the way of Toolbox commands. 


This means that this program is approximately 30% machine 
code. This percentage is often even greater as you use 


more and more Toolbox commands. 


80 


\ 


\ 
| 


Pea bet esd fi bemead P Pee ms 


® ® 
es ae 1 | 


LI 


{i 


a 


ms ™ 


-~ 


THOR HH MH 


| 


The net result is that you~1l find that even though 
it appears you are writing a program in BASIC, it is not 
unusual to find that over 50% of the final program is 
written in fast and compact machine code! 


HI-RES GRAPHICS AND THE MEMORY MAP 


The most important function of the memory map is if 
you are using Hi-Res graphics in your program. Because 
the Hi-Res page occupies the middle memory range of your 
computer, an Applesoft program can become so long as run 
into the area used for graphics. The symptoms of this 
are program crashes after an HGR or HGR2, or strangely 
changing variable values while using graphics. 


The memory map can be used to predict when a problem 
is likely to occur. 


1. If the ACTUAL PROGRAM END value is greater than $2000 
($4000 if you are using HGR2), then your program is too 
long. 


Solution: Remove REMark statements from your program and 
take other steps to shorten the length of the listing, 
such as combining lines where possible. You can also use 
utilities such as Roger Wagner Publishing”s APPLE-DOC II 
to compress your BASIC program, or use the Chart “n Graph 
Toolbox to move your program above the Hi-Res page. 


You can also add the following line to your program: 


2 IF PEEK(104)=8 THEN POKE 104,64:POKE 16384,0:PRINT 
CHRS(4);"RUN MYPROGRAM": REM FOR HGR USE 


or: 


2 IF PEEK(104)=8 THEN POKE 104,96:POKE 24576,0:PRINT 
CHRS$(4);"RUN MYPROGRAM": REM FOR HGR2 USE 


where “MYPROGRAM” is the name of your program as 
stored on the diskette. 


If your program does not exceed $2000 (or $4000 for 
HGR2), then you should also remember to always use a 
LOMEM: 16384 (24576 for HGR2) as line 2 of your program. 


If you are unfamiliar with the other memory locations 
mentioned in the memory map, we recommend “ALL ABOUT 
APPLESOFT", available from local computer stores and also 
from Roger Wagner Publishing. 
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APPENDIX A 
READING AND WRITING MULTI-—DIMENSIONAL ARRAYS 


Multi-dimensional arrays may be Read into and Written 
from with ARRAY READER.TB and ARRAY WRITE.TB. Unless 
certain precautions are taken, however, some unexpected 
results may be observed. The basic problem lies in how 
Applesoft stores the elements of a multi-dimensional 
array and how we (programmers) think of arrays. Apple- 
soft stores array elements with the LEFT most array index 
ascending fastest. This means that for an array with the 
dimensions A(4,5) the elements would be physically stored 
in memory as follows: 


A(O,0)5;A(1,0)3A(2,0)5A(3,0)5A(4,0)5A(0,1);A(1,1)3A(2,1) 
etc. 


Most programs published in periodicals, privately 
written or commercially available use arrays in the 
opposite fashion, (i-e- A(0,0);A(0,1);A(0,3);etc.). Many 
people have seen a record management program somewhere 
that assumes elements A(49,1) through A(49,10) constitute 
one complete record. 


It is convenient for us to picture data stored in 
this fashion and the beauty of the computer is we CAN 
think of it this way and not USUALLY run into any 
trouble. When using advanced programming techniques 
(i-e. machine language subroutines) it sometimes is 
required to think in the same fashion as the machine in 
order not to run into trouble. 


The potential problem will arise when someone who 
thinks like a human and not a machine writes a Basic 
routine to write data to the disk similar to the 
following: 


100 FOR I=1 TO 50 

110 FOR J=1 TO 20 

120 PRINT A(I,J): REM PRINT TO DISK 
130 NEXT 

140 NEXT 


What has happened here is that the data in memory has 
been interleaved with itself in order to keep the 
“records” physically together on the disk. If they were 
to be read back in to memory using a similar routine 
there would be no problem. 
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But consider what would happen if the data was placed 
back into memory in the same order as it was physically 
placed onto the disk: 


A(1,1)3;AC1,2)3A(1,3);A(1,4)---A(40,20)5A(50,1) etc. 


This is in conflict with the machine”’s idea of how 
the data should be stored. If the data were in fact read 
in this way what would appear to be element A(5,5) would 
in reality be A(45,1); the data was transposed. This 
works fine if you”re working with “square” arrays, only 
the indices need to be interchanged, but if youre 
working with “rectangular™ arrays the data sometimes 
becomes skewed, depending on the following equation: 


IF (DIM 1 MOD DIM2) <> O THEN SKEWED 


In any event, the data is always scrambled in some 
way and _ becomes difficult, if not impossible, to 
reconstruct. 


Why dwell on this subject for so long if consistent 
programming practices result in no_ problems? The 
Database Toolbox ARRAY READ and WRITE commands read and 
write data to and from memory in the order in which it is 
physically stored in memory, with the left index arising 
fastest. If data is written to the disk in BASIC using 
the wrong sequence and then is’ read using ARRAY READER 
then our problem will surface. If it is written using 
ARRAY WRITE and read using the wrong algorithm, again we 
will have our problen. 


Another practice that May cause the programmer 
trouble is ignoring the zero“th row and column of an 
array, assuming two dimensions. When an array is 
dimensioned in Applesoft to, say, 20 by 20, Applesoft 
actually allocates an array that is 21 by 21 elements. 
Where did the extra elements come from and how are they 
accessed? 


If the array were addressed as, say, A(21,21) a BAD 
SUBSCRIPT error would result. That means Applesoft isn“t 
adding the extra elements at the “top” of the dimensions. 
If it were addressed as A(0,0) no error occurs, so _ that 
must be where the “hidden” elements are. In fact, witha 
20 by 20 array there are 39 such hidden elements. They 
would be the ones that had a zero as either one of the 
indices (i.e. A(0,0),A(13,0),A(0,9) ). 


The potential problem arises in much the same way as 
the previous problem, inconsistant programming. Since 
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most programmers don”“t use the zero”’th elements of an 
array, they certainly don”t want to waste time or space 
by storing them on the disk. They usually use an 
algorithm similar to the following one to store an array: 


FOR I = 1 TO 10 
FOR J = 1 TO 10 
PRINT A(J,1) 


Thinking back to the previous discussion on skewing 
data while reading, the current problem comes into focus. 
If we read an array stored in such a way using ARRAY 
READER.TB and place it starting in element A(1,1) the 
data locations within the array will again be wrong, 
except for the first column. Elements A(1,1)..-A(10,1) 
will all be correct. But the next element in memory is 
not A(1,2) as would be expected, but is A(O,2)! The net 
result being column #1 is correct, every other column is 
shifted up one element. 


What can be done to avoid this problem? The best 
answer is to use ARRAY READER.TB' and ARRAY WRITE.TB to 
store and recall all arrays since they are always 
compatible. If this is not practical then one of the 
following tips should help. 


If it is required to read a file stored using the 
“problem” method, read it starting at element A(0,1). 
This will result in every column being shifted up one 
element. The array indices may then be adjusted to 
compensate for the data relocation, this can be rather 
messy at times, however. 


A more elegant solution is to use ARRAY ROW COL 
ADD.TB to add a new row zero! This will shift all data 
down. one element, clear the zero”°th row and solve the 
problen. 


A-similar method may be used to write arrays that 
must be read using the “problem” method. Just “kill” row 
zero and write from A(0,1) on up! 


The simplest solution is to be aware of the structure 
of Applesoft arrays, program accordingly, or use row and 
column zero! Youll save a headache and gain some space! 


In summary, when using multi-dimensional arrays, 
these commands will handle arrays of any number of 
dimensions, just be consistent in how data is read and 
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written to the disk. The problems discussed will not 
happen as long as some thought of the machines version 
of reality is given. 


ARRAY WRITE AND THE “DATA BUFFER” 


The data buffer used by the ARRAY WRITE.TB command 
holds the data to be written to disk after it is 
retrieved by the command and set up for disk storage. 
The location of the buffer defaults to the following: 


ST= end of array storagetl 
EN= start of string storage-l 


These are the values used if no buffer variables are 
specified in the command. If there are no machine 
language programs or data residing in this area or if the 
Hi-Res graphics are not in use this method of storage is 
preferred. If however, there is some part of memory that 
must be protected, the buffer variables allow the 
programmer the ability to protect it. When using a 
smaller buffer it is possible to slow the command down 
depending on the size of the buffer and the size of the 
array and its data. 


The optimum buffer size may be determined for string 
arrays in advance by the program if required. There is 
no simple way to determine the minimum buffer size 
required for integer or floating point arrays. but any 
technique used to optimize the buffer size will waste 
much more time than is required to fill and write the 
buffer a number of times. The implications of the last 
statement are very important for a full understanding of 
ARRAY WRITE.TB. The command will fill the buffer with 
data and write it to disk as many times as are required 
to write the entire array. 


Since AKRAY WRITE’s defaults for buffer size depend 
on the amount of variables in use, as well as the amount 
of strings (allocated and dead) and the program size, it 
may be prudent to house clean prior to an ARRAY WRITE in 
order to obtain the largest possible buffer and fastest 
write. 


The END variable is subject to a restriction. It is 
not allowed to be specified alone. It must be preceeded 
by the START variable. This is not really a problem 
since it is possible to specify the default start with 
the START variable. 
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In order to do this a statement such as the following 
could be used: 


10 & “WRITE”,"W",FS,E,AS(1) TO A$(99),PEEK(175)+ 
PEEK(176)*256+1, EN 
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APPENDIX B 
ADVANCED USE OF THE TOOLBOX SERIES 
1. USING CALL STATEMENTS IN TOOLBOX COMMANDS 


Normally, the pointer that Applesoft uses to indicate 
the end of the Applesoft program in memory does in fact 
point at the end of the last line of a program. 


However, it is possible to redirect this pointer so 
that it points to a location some distance after the end 
of the BASIC lines in a program. This in effect creates 
a "pocket" at the end of a program into which may be 
placed machine language programs. 


The beauty of this approach is that when the program 
is loaded or saved to disk, or even when lines are 
changed, added or deleted from the program, the pocket 
within the entire Applesoft program “envelope” (i.e. the 
portion of memory between the start-of-program and 
end-of-program pointers) is protected and carried along 
with the BASIC program. 


Once a command has_ been added in this manner, the 
question arises as to how it is to be called by the 
Applesoft program. If the command is to be added to a 
finished Applesoft program, and that program is always 
run at the same address in memory, then you could 
conceivably CALL the command at a fixed address. 


This method, though, is not very practical, since 
programs are often changed, with the result that the 
absolute memory locations of any appended routines change 
accordingly. 


Fortunately, there is an alternative. If one machine 
language routine of length N bytes is appended to the end 
of an Applesoft program, then the address of the first 
byte of the routine will always be found at the address 
of the end of the program minus N. (The term “program” 
here means BOTH the BASIC portion together with the 
appended machine code.) That is to say, one would look at 
the value contained in PRGEND (the pointer to the end of 
program: 175,176) to determine the end of the program 
“envelope”, and then subtract N bytes. 


Thus the routine could be called at the address: 


PEEK(175) + 256 * PEEK(176) - N 
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This address will remain valid despite any changes in 
the length of the BASIC portion of the program, since the 
pointer at locations 175,176 (PRGEND) always points to 
the end of the program envelope. 


This method can be generalized to accommodate more 
than one appended routine, but to append several routines 
by hand can be rather tedious. Fortunately, you dont 
have to, since the Workbench will do it all for you! 


Whenever you have added routines to your program 
using the Workbench, there will also be present a machine 
language routine which handles the initial part of your 
Toolbox command. This routine is automatically included 
in your program when you add the first command. 


This routine is known as_ the “Interface Routine” 
because it acts as an interface between your Applesoft 
program and its appended machine language routines. 


It is always placed at the very end of the program 
envelope, and occupies the last 203 bytes. Thus it can 
be called at the address: 


IR = PEEK(175) + 256 * PEEK(176) - 203 


This is the address set up in line #1 of your program 
by the EXEC file on the Database Toolbox diskette named 
CALL SETUP. 


When, during the course of the execution of your 
Applesoft program a Toolbox command is called (by one 
means or another), the first thing that happens is that 
control passes to the Interface Routine, which then looks 
at the command name (between the quotes) in an attempt to 
find out which particular command you’re interested in. 


With the name in hand it then searches through the 
commands added, and if it finds the one you want then the 
Interface Routine passes control on to that routine. 


2. USING THE AMPERSAND IN TOOLBOX COMMANDS 


Although the routines can be called using the CALL 
statement, there is a more efficient method, using the 
ampersand. 


At locations $3F5-3F7 (decimal 1013-1015) is a JMP 
instruction (see the Apple ][ Reference Manual, p. 132). 
If the address of the Interface Routine is placed into 
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locations 1014 (low byte) and 1015 (high byte), then when 
the Applesoft interpreter encounters the ampersand 
character (&), control will pass to the Interface 
Routine. As before, the routine will then locate the 
command that you wish to use, and pass control to it. 


Thus in this system there are TWO distinct ways of 
calling added commands. The effects are the same, and 
only the syntax of the Toolbox command varies. Below are 
examples of commands using each of the two methods: 


CALL IR "SWAP", AS, BS 
& "SWAP", AS, BS 


CALL IR “SORT”, AS(FE) TO AS(LE) 
& "SORT", AS(FE) TO AS(LE) 


The two methods have the same _ result: To call the 
Interface Routine, which then reads the name of the 
command, locates it in memory (somewhere between itself 
and the end of the BASIC portion of your program), and 
then JMPs to the routine. 


If the CALL method is used, it is necessary to have a 
statement in your Applesoft program which defines the 
CALL address “IR“. Such a statement can be inserted in 
your program (as line #1) by EXECing the file CALL SETUP 
on the Database Toolbox diskette (with your program in 
memory, of course). 


If the ampersand method is used, then the ampersand 
vector must be set up to point to the address of the 
Interface Routine. This can be done by a CALL to an 
internal entry point in the Interface Routine itself. 


This internal entry point is 46 bytes before the end 
of the Interface Routine, which is itself at the end of 
your Applesoft program, and so the required ampersand 
vector setup can be accomplished with a simple 


CALL PEEK(175) + 256 * PEEK(176) - 46 


The file AMPERSAND SETUP on _ the Database Toolbox 
diskette can be EXECed to insert this line (as line #1) 
in your program. 


Then when your program is run the ampersand hook-up 


is automatically made and your program can then use the 
ampersand for added commands without further thought. 
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It is up to you which method you wish to use to 
call commands. The ampersand method is more pleasing to 
the eye, and also involves fewer keystrokes, but it does 
modify the ampersand vector which may _ be used by other 
utilities. If you wish to use ampersand utilities, you 
may care to use the CALL IR method of calling Toolbox 
commands. It is also possible that you might have an 
ampersand routine that is entirely independent of the 
Toolbox system. In that case, the CALL IR method will 
leave the ampersand free for other duties. 


If you are still unsure as to the difference between 
these two methods of calling commands, then simply ignore 
the existence of the CALL method, and stick to ampersands 
(they~1l1 never let you down). 


3. RESTORE AMPERSAND.TB 


A possible conflict can arise between the use of the 
ampersand to call Toolbox commands and its use with 
utilities such as Apple Computer’s Renumber routine. 


If the ampersand has been set to “point” to one 
particular utility, such as a Renumber Program, then when 
a program using a Toolbox command runs, this pointer is 
lost because the Toolbox system takes over the use of the 
ampersand. 


There are two solutions to this problem. The first 
is to call commands using a CALL directly to the 
Interface Routine as described in the previous section on 
CALLs. 


If this method is used then the ampersand vector is 
not reset when your program is run (unless your program 
resets it in some other way), and so your ampersand- 
related utility is always connected. 


However, normally the method of calling commands by 
means of the ampersand is preferable. In this case we 
may employ a Toolbox command to solve the problem. When 
your program is run, the line which causes the ampersand 
vector to be reset to the Interface Routine also causes 
the old ampersand vector to be saved. 


Included on your Database Toolbox diskette is the 
command RESTORE AMPERSAND.TB. This can be added to your 
program like you would any other command. It should then 
be used just before your program ends; it has the effect 
of restoring the original ampersand vector. Therefore on 


90 


5) 
| 


% 
[ 


ce) oS) ee) OS ee 


\ 


4 


Om & 


Om ® 


® 


| 
\ 


fall ‘fall 


14 


i 


return to immediate command mode your ampersand-related 
utility will have been reconnected and will be ready to 
be used. 


If the RESTORE AMPERSAND.TB command is used, it MUST 
be the LAST Toolbox command used before your program 
comes to an end. If not then a_ subsequent Toolbox 
command will have the effect of calling your utility 
from within your program, usually with unpredictable 
consequences. 


4. Using JUMP FILE CREATE 


There is a wealth of relocatable routines available 
for performing all kinds of tasks in the other Toolbox 
library disks. Thus normally you will not have to be 
concerned with interfacing any non-relocatable routine 
with an Applesoft program. However, it may be that you 
already have a routine which you have been using at a 
fixed address and which is not relocatable. Such a 
routine cannot be used directly as a Toolbox command. 
There are, however, two possible solutions. 


The first is to take your routine and make it 
relocatable. If this cannot easily be done then there is 
a utility on the Database Toolbox diskette called JUMP 
FILE CREATE to provide aid and solace. 


Using this utility you can create an intermediate 
calling routine which will function as a link between the 
Interface Routine (appended to your Applesoft program) 
and your non-relocatable routine (occupying its required 
position in memory). 


The only requirement for using JUMP FILE CREATE is 
that you know the address of the routine which would 
normally be CALLed (or used via an ampersand). 


For example, let”s suppose that the file BEEP.TB were 
a nonrelocatable routine which MUST be loaded at location 
$300 (decimal 768) to function properly. To create an 
interface command, run JUMP FILE CREATE. 


You will then’ be presented with the opportunity to 
enter the call address in decimal. If you do not know 
the decimal address, press RETURN and a hex option will 
be presented. For our example, enter “300° as the hex 
address. It will then print out the decimal equivalent 
as a matter of information, and instruct you to _ press 
“S“to save the file. 
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It will then be saved to the Toolbox diskette as 
- IMP .$0300/768.TB~. This Toolbox File could then be 
added to your program like any other Toolbox File, using 
the Workbench. If when adding the JMP file, you specify 
“BEEP" as the command name, then your program could use 
BEEP.TB as follows : 


1 CALL PEEK(175) + 256 * PEEK(176) - 46 
10 PRINT CHRS(4);"BLOAD BEEP.TB, A$300" 
20 INPUT "PITCH,DURATION? "; P, D 

30 & "BEEP", P, D 


If you wish to write your own machine language 
routines, the Toolbox system is an ideal way to interface 
them to an Applesoft program. 


In addition, the following aids are available through 
Roger Wagner Publishing: 


* MERLIN, an extremely powerful, yet easy to use 
macro assembler. Besides being one of the _ best 
assemblers for the 64K Apple II, II+, //e or //c, 
MERLIN offers additional features like Sourceror, 
which disassembles raw binary code into pseudo 
source files, and a fully labeled and commented 
source listing of Applesoft BASIC. MERLIN also 
uses the upper 16K of memory to become a 
co-resident assembler with the ability to easily 
switch between MERLIN and Applesoft. 


* MERLIN-PRO, the PROFESSIONAL version designed 
specifically for the 128K //e or //c, comes with 
both DOS 3.3 and ProDOS diskettes. In addition 
to the standard MERLIN features, MERLIN-PRO also 
offers a Relocating Linker to generate relocatable 
object code, a macro library, local labels, and 
support for 6502, 65C02 and 65802 opcodes. Also 
includes SOURCEROR, a symbolic disassembler to 
create source code from binary files, handy cross 
reference utilities, and SOURCEROR.FP which will 
produce a fully labeled, commented, and cross- 
referenced source listing of Applesoft BASIC. 


* ASSEMBLY LINES: THE BOOK, is a beginning tutorial 
on machine language programming. There is a 
section on creating relocatable code, and also 
other topics such as sound generation and disk 
1/0. 
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* ASSEMBLY LINES: THE DISK, contains over 50 source 
listings and assembled object files as listed in 
Assembly Lines: The Book. No_ need to type in all 
those lengthy listings, they”~re all here on one 
handy diskette. 


* MUNCH-A-BUG, an excellent de-bugging package for 
machine language programs. Allows use of labels 
and includes its own mini-assembler. Best of all, 
it can be set in a “waiting” condition to go into 
the trace mode only after a given routine has been 
called, thus allowing the user to trace machine 
code from within fully operational Applesoft 
programs. 


* APPLESOFT IN DEPTH, is an extensive study of 
Applesoft and related routines. Published by CALL 
-A.P.P.L.E., this is an invaluable reference book 


for programmers. 


* THE WIZARD“S TOOLBOX I. This was the original 
Toolbox package and contains additional informa- 
tion not found in the other library packages on 
writing your own Toolbox commands. 


On the other hand, if you are unable or not inclined 
to delve into what may seem to you the Terra Incognita of 
assembly language programming, yet find yourself in need 
of a command to do a certain task, then please contact 
Roger Wagner Publishing. 


Although we do not usually produce custom Toolbox 
commands, requests of general interest do often result in 
new Toolbox commands, and we“1ll be sure to let you know 
if a command that interests you becomes available. 


KHEKK KER AEKRKKE KEKE ERK RE REE IEREREEREREREREREREREREREREEERE 
IMPORTANT: IF YOU DO WRITE YOUR OWN ROUTINES, 
PLEASE WRITE ROGER WAGNER PUBLISHING! WE MAY BE 
ABLE TO INCLUDE THE ROUTINE ON FUTURE TOOLBOX 
COMMAND LIBRARY DISKS! WE CAN ALSO SUPPLY INFOR- 
MATION AS TO WHAT ROUTINES ARE CURRENTLY UNDER 
DEVELOPMENT, AND WHICH ARE STILL NEEDED. 
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APPENDIX C 
A LITTLE MORE DETAIL 


The information in this section gets a bit technical. 
It is included here for the enjoyment of the programmer 
that wants to know more about how the Toolbox actually 


operates. 


Although it is not necessary to understand all the 
information provided here to use Toolbox system, it may 
help you get a better feeling for what you are actually 
doing when you use it. In addition, there is a descrip-— 
tion of the conflict between a long Applesoft program and 
the Hi-Res pages, which may be helpful if you are using 
graphics. 


When you first specify the name of a command to be 
put in your Applesoft program, the Workbench does the 
following things: 


1) It appends the Toolbox File to the end of your 
Applesoft program. Because of the nature of Applesoft, 
this machine code is not visible during a LIST, and is 
unaffected by adding or deleting normal BASIC lines or 
statements. 


2) It saves both the name you give to use _ the 
routine, and the name of the disk file loaded. This is 
to make later identification of commands easier (see the 
section on the Command Report). 


3) The first time a command is added, the Workbench 
adds its own “Interface Routine” to the end of your 
program. The function of this is to locate a module 
named in a Toolbox command and to pass control to it. 


The manner in which memory is normally allocated in 
the Apple computer is as follows: 


| | LI | 
[FP | |DOS|ETC. | 
| PROG. | | | | 
| | | | 
“$800 *LOMEM “HIMEM 


Figure 1: “Normal” Applesoft program 
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Normally an Applesoft program resides at the “bottom” 
of memory, with all remaining space above it reserved by 
DOS and for variable storage. 


The Workbench could be loaded right after your 
program, but as Toolbox Files were added to the end of 
the Applesoft program, they would start to conflict with 
Workbench itself. To avoid this, the Workbench moves 
your program UP in memory, and locates itself at memory 
location $800 (the dollar sign indicates a hexadecimal 
address). 


| | | | | 
| WORK- | FP | T. B. |INTER-| |IDos|ETC.| 
| BENCH |PROG.|MODULES|FACE | | | | 
| | | | | 
*$800 ~$2600 *LOMEM “HIMEM 


Figure 2: With the Workbench loaded 


With your program safely relocated to $2600, routines 
are automatically placed between the Interface Routine 
and the end of your program (“FP PROG” on the chart). 
When your program is run, the Line #1 that was put in by 
the AMPERSAND SETUP file points the ampersand vector to 
the Interface Routine at the end of your program. From 
there the name following the ampersand is read and _ the 
proper routine used. 


CAUTION: Note that your program now STARTS at $2600. 
This is well into the Hi-Res page 1 display, which 
normally starts at $2000. Thus, any program using an HGR 
command will destroy itself if you attempt to run it with 
the WORKBENCH in memory. The Workbench must be removed 
before running any program using Hi-Res graphics. 


| | 1 | | 
|FP | T. B. [INTER-| |DOS|ETC.| 
|PROG.|MODULES|FACE | | | 
| | ) | | 
“$800 “LOMEM “HIMEM 


Figure 3: At “Run Time” 
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If you use the REMOVE WORKBENCH utility, or doa 
fresh load of an Applesoft program containing appended 
modules after entering “FP”, then memory will be allo- 
cated as in Figure 3. This shows’ the Applesoft program 
back at its normal location, with the appended routines 
and the Interface Routine still present. 


Hi-Res graphics on page 1 will in most cases now be 
available. When in doubt, you can use the Memory Map 
option from the Workbench (see p-27 of this manual) 
showing the addresses for your program at its normal 
location of $801. 


When developing a program using Toolbox commands, you 
can proceed in three ways: 


1) Add commands to your program, one at a time, as 
required. 


2) Work on the BASIC portion of your program first, 
and then add the required commands later, or 


3) Add all required commands and then write the 
BASIC portion of the program which calls them. 


HI-RES GRAPHICS, RENUMBERING AND 
OTHER HAZARDS TO THE TOOLBOX 


Improper use of Hi-Res graphics, or use of Apples 
Renumber program can destroy added Toolbox commands in 
your Applesoft programs. 


If you are using Hi-Res graphics with the Toolbox 
system, you should be _ sure to read the section on the 
Workbench’s MEMORY MAP option. This will help you avoid 
having an HGR or HGR2 command destroy added Toolbox 
commands. 


If you are using Apple“s Renumber program, be sure 
to read the section in this manual on COPYING ALL 
COMMANDS TO DISK in the Workbench. 


If the worst should happen and your added Toolbox 
commands are damaged, you will be able to tell because 
the Workbench main menu will say NO COMMANDS ADDED, and 
option #3 will now say REMOVE APPENDED MACHINE CODE. 
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This is because the Workbench can tell that you have 
something (destroyed Toolbox commands probably) still 
added to your program, but it doesn“t recognize it as the 
Toolbox commands. 


This can be verified by going to the MEMORY MAP, 
where the screen will now display BYTES APPENDED where 
it used to read TOOLBOX BYTES ADDED. Again, the 
Workbench is telling you that something is left hanging 
on the end of your program, but it doesn”t know what. 


If this should happen, you will have to use option 
#3 to remove the damaged Toolbox commands, and then 
individually re-add the various Toolbox commands used by 
your program. Option #7 may be helpful here as it can 
be used to list all the Toolbox commands called by your 
program. 
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APPENDIX D 
USING THE TOOLBOX AND WORKBENCH WITH ProDOS 
The Toolbox and Workbench are ready to run with ProDOS. 
CONVERTING FILES TO ProDOS 


You will need to use Apple”~s CONVERT program to convert 
all files on the disk to the ProDOS format. You will also 
have to place a copy of the PRODOS system file as well as 
the BASIC.SYSTEM file on the disk. After converting your 
files, you should rename HELLO to STARTUP. 


INCOMPATIBLE COMMANDS 


Please note that the following Toolbox commands will not 
work with ProDOS: 


ARRAY READER.TB 
ARRAY WRITE.TB 
DISK START UP.TB 
FAST FP RUN.TB 
FAST BRUN.TB 


The READ and WRITE commands when written for ProDOS do 
not increase the speed of reading or writing data- The 
other commands are also not required due to_ the 
increased speed of the ProDOS operating system. 


In addition, the GARBAGE MAN.TB' routine is not needed 
with ProDOS. You can substitute the following every 
where you would have used the GARBAGE MAN command: 

PRINT CHRS(4) “FRE” 


FRE is the ProDOS command that can be used to force 
quick house cleaning (or garbage collection). 


FILE NAMES AND PATHNAMES 


You will notice when you have CONVERTed your files, that 
the file names have been changed. All spaces and symbols 
(e.g. & *, #, etc.) have become periods (.). In 
addition the names have been shortened if they were 
longer than 16 characters. You may wish to rename the 
files after conversion. 


USE OF WORKBENCH 
The Workbench works as it does under DOS 3.3. 
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NOTE: This list is provided solely to refresh your 
memory as to the exact syntax of any given command. It 
is assumed you have already read the primary reference 
section in the manual and are familiar with the command. 


ARRAY haart (pg 14) Length = 981 bytes 
“READ”, sexp, sexp, [ aexp,] avar, avar 
t array var ] 
& “READ”, "R", "FILE", N, E, A$(1) 
& “READ”, “M", “FILE”, S, N, E, A(1,1) 
& “READ”, “N", “FILE”, N, E 


ARRAY ee a (pg 17) Length = 865 bytes 
& “WRITE”, sexp, sexp, avar, array var TO array 
var [, aexp [, aexp ] 
& “WRITE”, “W", "FILE", E, A(1) TO A(100) 
& "WRITE", “cn, “FILE”, 25) sAS (1) e210) ae 
& & "WRITE", O$, FS, E, A$(1) TO AS(J), ST, EN 


ARRAY SEARCH.TB (pg 21) Length = 659 bytes 
>> MULTI DIMENSIONAL ARRAY << 


& “ARYSRCH”, array svar (avar, avar) TO array 
a (aexp, aexp), sexp, [, avar] [, aexp] [, 
aexp ]} 

& ARYSRCH”, AS(ROW,CS) TO AS(ROW, CE), KWS 

& “ARYSRCH”, AS(RS,COL) TO AS(RE, COL), KWS 

vaaeeicnas *as(R, C) TO AS(R,E),KWS,CP, ,BB, ST 


>> SINGLE DIMENSION ARRAY<< 


&"ARYSRCH", array svar (avar) TO array svar 
(aexp), sexp [,avar] [, aexp] [,aexp] 
&"ARYSRCH", AS(ST), KWS 

&"ARYSRCH", AS(ST) TO AS(EN), KWS,CP »BB,ST 


ARRAY SORT.TB (pg 27) Length = 751 bytes 
>> MULTI DIMENSIONAL ARRAY << 
&"SORT", array var (aexp,0) TO array var 
(aexp,0) ON array name% (0) 


&"SORT", AS(ST,0) TO AS(EN,O) ON KEY%(0) 
&"SORT", X(ST,0) TO X(EN,O) ON KEY%(0) 


FY 


fi =; — & "SORT", array var (aexp) TO array var (aexp) 


ss ON: array name%(0) 
al ake &"SORT”, AS(S) TO AS(E) ON KYZ(0) 
&"SORT”, ZZ(1) TO ZZ(100) ON K%Z(0) 


DELIMITED STRINGS.TB (pg 33) Length = 960 bytes 
Commands: 


FIND: &“DSTR", “F[IND]”, array svar, avar, svar 
[,avar] [,avar] 
&"DSTR", “F", AS(I), F, A$ 
&"DSTR", “FIND”, A$(55), F, F$, S, L 
&"DSTR", O$, AS$(I), F, AS,,L 


SEARCH:&"DSTR", “SE[ARCH]", array svar [ to array 
svar] , avar, svar 
&"DSTR”, “SEARCH”, AS$(1), FIELD, KEYS 
&"DSTR", "SE", AS(I) TO A$(100), F, KY$ 
&"DSTR”, O$, AS$(I) TO AS(J), F(1), KY$(10) 


SORT: &"DSTR", “SO[RT], array svar [ TO array svar] 
>» avar 
&aDSTR* se 7SORT>,, AS(1)" 521 
&"DSTR”, “SO”, AS(1) TO A$(100), F 
&"DSTR", O$, AS(L) TO AS(J), F(K) 


REPLACE:&"DSTR", “R[EPLACE], array svar, avar, sexp 
E“DSTR®, “Rs ASC), F, RS 
“DSTR", “REPLACE”, AS(J), 3, “ARRAYS” 


ARRAY RENAME.TB (pg 38) Length = 186 bytes 
&"RENAME”, array varl, array var2 ({array var3, 
array var4}] 

&"RENAME”, A(O), B(O) 
&"RENAME”, AS(0),B$(0),C%(0) ,DZ(0) 
&"RENAME”, Z(0,0), A(0,0) 


ARRAY CLEAR.TB (pg 39) Length = 74 bytes 
&"CLEAR", array var [{,array var}] 
&"CLEAR”, AS(0) 

&"CLEAR”, A$(0),B(0),2%(0) 


ARRAY DELETE.TB (pg 40) Length = 113 bytes 
&"DELETE”, array var [{,array var}] 
&"DELETE”, A(0) 

&"DELETE”, A(0),B(0,0),C%(0) 


FRR eae 


ARRAY mene (pg 41) Length = 978 bytes 
&"REDIM", array name (aexp, aexp) 
&°REDIN" ACI,J) 
&"REDIM", A%(5, KG) 


ARRAY Bey te (pg 42) Length = 132 bytes 
&" TRANS” array! (subl) TO ae (sub2), array2 
&"TRANS", AS(1) TO AS$(100), BS 
&" TRANS", NAS(1,10) TO ecto BS(1) 


ARRAY ROW COL ADD.TB (pg 45) Length = 492 bytes 
&"ROW COL ADD", rears name (avar, avar) 
&"ROW COL ADD", A(I,J) 
&"ROW COL ADD", XS$(ROW, COL) 


ARRAY ROW COL KILL.TB (pg 45) Length = 447 bytes 
&"ROW COL KILL", array name (avar, avar) 
&”ROW COL KILL”, A(I,J) ; 
&"ROW COL KILL", Z$(ROW, COL) 


ARRAY aurea (pg 47) Length = 374 bytes 
INCT”, array avarl = array avar2 aop aexp 
ENG: A(O) = B(O) * 1 


ARRAY FUNCTIONS SINGLE (pg 47) Length = 297 bytes 
&"FUNCS", array avarl = func array avar2 
&"FUNCS", A(O) = PEEK(C(0)) 


_ ARRAY RANDOM.TB (pg 47) Length = 241 bytes 
‘&"RND", array avar = RND (aexp) 
&"RND", A(O) = RND(1) 
&"RND", Z(0) = RND(Q) 


ARRAY FUNCTIONS PARSE.TB (pg 47) bere h = 314 bytes 
&"PARSE”, array var = exp 
&"PARSE”, X(0) = ae te “E02 
&"PARSE”, X(0) = Q(O * 10) 


ARRAY ae (pg 50) Length = 414 bytes 
& “ARYSTR" , suray, avar [, array svar] 
&"ARYSTR", ACO 


&"ARYSTR", A(O), BS(O) 


ARRAY VAL.TB (pg 52) Length = 238 bytes 
&"ARYVAL", array avar = VAL array svar 
eae A(O) = VAL (AS(0)) 
&"ARYVAL", A(ST) = VAL (ST$(0)) 


ARRAY ROUNDING.TB (pg 53) Length = 187 bytes 
&"ROUND", array avar TO aexp 
&"ROUND", Y(0) TO X 


eee ence (0,0) 
> EO0) 


LY.7B (pg 55) Length = 507 bytes 

: ey array avar (0,0) = array avar (0,0) * 
"Sieoee s teeeey avar (0,0) 

&"MUL", A(O, Dy = B(O,0) * C(0,0) 


ee OS 5 (pg 56) Length = 1088 bytes 
&"INV”, array avar (0,0) , avar 
&"INV", A(O,0), DET 


USR MACHINE.TB (pg 56) Length = 121 bytes 
&"USR MACHINE”, usr routine name 
&"USR MACHINE”, “USR ARC SIN” 
&"USR MACHINE”, USS 


USR FUNCTIONS (pg 58) 
avar = [ expr ] USR (aexp) 
X = 5 * A + USR (5) 
X = SIN (USR(A/39) )+3 


RND FIX.TB (pg 60) Length = 22 bytes 
&"RND FIX” 
ONERR-TB (pg 61) Length = 38 bytes 


&"ONERR”, GOTO line num 
&"ONERR”, GOTO 100 


RETURN FIX.TB (pg 62) Length = 22 bytes 
&” RETURN” 


GARBAGE MAN.TB (pg 63) Length = 487 bytes 
&"GARBAGE" [, avarl] [, avar2] 
&" GARBAGE” 
&" GARBAGE” , FR 
&’ "GARBAGE" , »FR,ST 


anek 
DISK START UP.TB (pg 65) Length = 127 bytes 
&"DISK START”, aexp, aexp 
&"DISK START”, 6,1 
Neer s,D 


a ° 


og Oo ® 8 GF Hh Me fe wh it fh dy Vy fy jy yy vy yy yy yk 


@SetC EEC CC ce LL eS e eee esau ss 


FAST FP RUN.TB (pg 66) Length = 706 bytes 
&"RUN", sexp 
&"RUN", “PART TWO” 
&"RUN", FILES 


FAST BRUN.TB (pg 67) Length = 622 bytes 
&"BRUN", sexp [, parameters] 
&"BRUN", “BINARY PROG” 
&"BRUN", "“WAIT.TB, 16384" , 5 


RESTORE AMPERSAND.TB (pg 68) Length = 18 bytes 
&" RESTORE” 


BEEP.TB (pg 70) Length = 56 bytes 
&"BEEP" [ ,aexpl] [,,aexp2 ] 
&"BEEP” or &”BEEP”,PITCH or &”BEEP”,PITCH,DURA 


>> POSSIBLE RUN TIME ERRORS...<< 
SYNTAX ERROR... 
1) Check syntax for the command youre using. 


2) Make sure the ampersand hook-up line (usually 
line number 1) has been installed and executed 
prior to the command being used. 


SYSTEM HANGS WHEN COMMAND IS USED... 


1) Make sure the ampersand hook-up line (usually 
line number 1) has been installed and executed 
prior to the command being used. 


2) If the command being called involves moving 
blocks of memory, make sure that the variables 
specified are appropriate. Also make sure that 
you are not overwriting critical areas of the 
Apple’s memory such as DOS, zero page, etc. 


UNDEFINED FUNCTION ERROR... 


1) Check to make sure you are using the same name to 
call a command as was used when first adding 
the command. You can use option #6 from the 
Workbench menu to review the names you gave 
commands as they were added. 


VT a ree aeen i | 


You're writing a program in Applesoft, 
and most of it’s complete. Now comes 
the part you've been avoiding — how 
to write a routine to sort your list of 
names by last name and zip code. 
You've spent hours scanning books, 
magazines and manuals trying to find 
something that you can use in your 
program. Nothing seems to work 


exactly the way YOU want, and worse _ 


yet, everything is in Bede which 
means itis slow! 
If this sounds familiar, the simple 
solution is The Database Toolbox. Just 
think of it as the original ‘APPLESOFT 


PROGRAM CONSTRUCTION SET™. 
With new and powerful commands 


not available in Applesoft or any 


language, you decide what you want _ 
your program to do, and The Database © 


- Toolbox will add a new command to 
Applesoft to do the work for you. The 
Database Toolbox gives you the speed 


of machine language routines and, 
best of all, it's EASIER THAN APPLE- _ 


SOFT! For example, sorting. a list of 100 
names is as simple as: 
: &“SORT’, , NAMES(1) TO NAMES( 100) 
ON KEY%(0) | 


The Database Toolbox contains all the 


easy to use commands you'll need to 
write any program that uses names, 


lists, or records such as personal 


mailing lists, recipe files, telephone 
lists, files on records, tapes, magazine 
articles, etc. 


With over 40 COMMANDS, you can 
aie or mort lists; quickly Read or 
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_ lists in one command. You can also 


Write lists to or from your disk; transfer 
parts of one list to another; or 
Redimension, Rename, Clear or Delete 


add or delete a row or column froma 
list. C 


There are 12 new USR math functions 
and matrix commands like Inverse, 
Transpose, and Multiply. You can 
perform math functions on entire lists 
at once with one simple statement. 


The Database Toolbox even has 


commands to fix bugs in Applesoft 
commands like ONERR, RND, and 


RETURN. There is a handy routine 
called Garbage Man which does 
string housecleaning up to 40 times — 


_ faster than Applesoft! 


‘The manual includes compe ir 


structions on each command, plus | 
hundreds of programming hints and 


/ tips on how to get the most from this ff 


‘Data Base Construction Set’. The § 
enclosed disk is packed with pro OC 


grams that demonstrate each ae 2 


every command. 


As a SPECIAL BONUS, you get afree ff. 


copy Of POSTMASTER, a complete — ip 
mailing label program that incor- 
porates many of the new commands. _ 
Use it as is, or list it and make any | 
modifications you may want. _ 
Finally, for your convenience, The 


Database Toolbox is UNLOCKED, | 


COPYABLE, 


| and HARD DISK 
COMPATIBLE. 


SYSTEM REQUIREMENTS: 
Apple Il, Il+, Ile or llc, with DOS 3.3 or ProDOS 
__ (Disk commands require DOS 3.3) _ T 
y, Ask your dealer for other Toolbox packages including The Chart 'n Graph ,j & 
Bi Toolbox, The Video Toolbox, and The Wizard's ees 1 


Dun eee 
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